Close this search box.

Home / Blog

How to efficiently rename PHP namespace without breaking backward compatibility

How to efficiently rename PHP namespace without breaking backward compatibility

Recently, we came across a problem, while developing a new version of the Notification plugin. We wanted to tidy up our codebase and one of the tasks was to rename some of the namespaces. But how to do it without copying the classes?

The requirements were simple:

  • Namespace needs to be mapped for changing on every level, ie. Namespace\X\Y\Z\Class but also Namespace\X\Y
  • We don’t want to copy each class into a separate namespace and maintain duplicates
  • We want to throw a deprecation notice if an old namespace is used

The solution is simple, and it’s a combination of class_alias() function and a custom autoloader. It doesn’t matter we’re using Composer as a main autoloader source.

Go ahead and change your namespaces directly in your source code, and define your autoloader.

spl_autoload_register(function ($class) {
	$deprecationMap = [
		'Namespace\X\Y\Z\Class' => 'Namespace\A\B\C\Class',
		'Namespace\Some\Other' => 'Namespace\SomethingCool',

	foreach ($deprecationMap as $oldNamespace => $newNamespace) {
		// Match the loaded classname.
		if (strpos($class, $oldNamespace) !== 0) {

		$newClass = str_replace($oldNamespace, $newNamespace, $class);

		if (! class_exists($newClass)) {

		$message = __('Class %1$s is <strong>deprecated</strong>! Use %2$s instead.');
		trigger_error(sprintf($message, $class, $newClass), E_USER_DEPRECATED);

		class_alias($newClass, $class);

Simply save this into a file and require it just after Composer’s vendor/autoload.php or use Composer autoload.files key to include your file.

This approach checks all the requirements, is simple, and doesn’t require copying your files and maintaining your code in multiple places. The class_alias() function is also compatible back to PHP 5.

Share This Article:

Picture of Kuba Mikita

Kuba Mikita

Share This Article:


Picture of Kuba Mikita

Kuba Mikita

Share This Article:

Latest updates, discounts and more!

Get the most recent updates on WordPress automation, fresh plugins, new features and price cuts.

Related articles

Following the success of the Notification plugin, we knew that personalization was the direction we would pursue. Thanks to feedback, we were easily able to identify the needs of the...

WordPress Cron is pretty basic and doesn’t allow for much configuration in terms of schedules. By default, you can run your events with a specific interval, like daily, weekly, or...

As a marketer diving into the technical realm, I’ve often highlighted the benefits of implementing a notification strategy on WordPress sites. Now, it’s time to delve into a more technical...

WordPress Plugins that get the job done

With years of experience creating client websites, we bring our experience to functional WordPress plugins.

Easy to use for everyone

Regardless of experience level, you can easily use our products.

Top-notch Support included

We treat our clients seriously and focus heavily on support. Reviews backs this up!

Extensible and developer friendly

You're the same developer as we are. Our code is clean and extensible, just the way you like.