PHP Backward Compatibility – Impacts of Using class_alias() to Maintain Backwards Compatibility in PHP

backward compatibilitynamespaceobject-oriented-designPHPrefactoring

Scenario: An open-source PHP project that has existed for several years has too many classes in the main namespace that we want to refactor some of them into another namespace, but we have a widely used and diverged plugin API, and refactoring may cause a major backwards incompatibility. This plugin API is basically loading external PHP files that interact with the classes and functions in the core code.

This project is not a Composer project (don't ask why), and it uses an class autoloading library maintained by ourselves.

I recently discovered the function class_alias, which might help with this problem.

I am considering refactoring the classes in the main namespace into a sub-namespace, and update references to them in the project. For the PHP files that originally contained the refactored classes (now they have been moved), I want to put something like this:

<?php
class_alias(NewClassName::class, OldClassName::class);

This will be loaded by the autoloading library when a plugin requires the use of OldClassName. I have tested this method and primary tests show that it works well.

Next step is to clean up the main namespace directory to fulfill the real motive of our refactoring – there are too many files in the main namespace directory. Hence, I am creating a new directory next to the source directory called als (alias directory), and making als a secondary source folder where alias class files are located.

Before, the project looked like this:

src/
    src/Foo/Bar.php

Now, the project looks like this:

src/
    src/Foo/Bar/Bar.php

als/
    als/Foo/Bar.php

Tests show that this method is working well so far.

However, are there any possible side-effects, from technical/performance perspective, documentation perspective or code structure perspective? We have never tried doing something like this and have never seen anyone doing this. Many developers are watching the repository for reference of the API, so we want to be more careful before trying these changes.

Best Answer

I have done it and it's possible, though there are a few pitfalls around autoloading to consider. I described the approach in a blog post:

PHP: Using class_alias to maintain BC while moving/renaming classes

Summary:

Do not put the class_alias() code into the original class file
The problem is that type hints do not trigger the autoloader. Similar to the ::class constant, type hints are resolved to a class name which is compared to the class name of the passed object, without actually looking for the type hinted class! That’s why it is important to have the alias in place as soon as the real class is loaded.

Otherwise passing a NewClass instance to the following function would fail because "NewClass" != "OldClass" and the alias is not defined yet:
```
function oldFunction(OldClass $old)
```
If you do not use composer or a single bootstrap file that is always loaded, the best way I found is to put class_alias() into the new class file:
```
\class_alias(NewClass::class, OldClass::class)
```
Then you have to make sure that the new class with the alias is also loaded if somebody tries to actually instantiate the old class (or use static properties, methods or constants). To do this, I trigger the autoloader in the old class file:
```
\class_exists(NewClass::class);
```

Related Solutions

PHP – Dynamic Class Inheritance Techniques

It looks like you are having a design issue here: Tables should not extend the Database Abstraction Layer. Instead the DAL should be injected into the table as a dependency.

abstract class Table {
    protected $dal;

    public function __construct(DAL $dal) {
        $this->dal = $dal;
    }

    // whatever else all tables have in common
}

class Table_User extends Table {
    public function someMethod() {
        $this->dal->someOtherMethod();
    }
}

$table = new MyTable($dal);
$table->someMethod();

That way you will create a DAL at some upper scope and pass it down. This will also allow you to use multiple different database engines at the same time.

Additionally you obviously should not create your tables directly in your controller but let a specialized class do that. For example you could use a factory:

class TableFactory {
    protected $dal;

    public function __construct(DAL $dal) {
        $this->dal = $dal;
    }

    public function createTable($name) {
        $className = 'Table_' . $name;
        return new $className($this->dal);
    }
}

That way you can create a table factory at some point with an injected DAL and pass that table factory around.

$table = $factory->createTable('User');

PHP Design Patterns – Single Class with Multiple Purposes vs Multiple Extended Classes

I think you are touching two often discussed topics here:

Monolithic classes vs small components
Composition vs inheritance

The following is a conclusion from what I've read and learned when I had similar problems to solve.

Monolithic vs components

Usually you should go for components that provide a model of the reality instead of building big monolithic blocks. Small components are easier to test and debug and harder to break.

Composition vs Inheritance

If you can go without inheritance you should. In your case the only common piece of File and Directory is that it has a path. Note the HAS A relation here. In fact the path is a property. Neither a directory nor a file is a path.

So - what you should go for is composition instead of inheritance. Please see http://en.wikipedia.org/wiki/Composition_over_inheritance for an introduction.

How to hold things together

Look for the factory pattern for returning a file or a directory depending on the type of file system object
Use an interface to define methods that both File and Path need to implement.
If both need the same functionality define a class for it. Usually the methods in this class are static. A trivial example would be a class FilesystemPermission that provides a method ::show($file_or_directory_object)

By the way - reading 'The Pragmatic Programmer' (look it up in the bookstore of your choice) covers such problems in depth - go for it if you haven't read it yet (every programmer should!).

Best Answer

Summary:

Related Solutions

PHP – Dynamic Class Inheritance Techniques

PHP Design Patterns – Single Class with Multiple Purposes vs Multiple Extended Classes

Related Topic