Class Alias Loader Laravel Package

Getting Started

Start by installing the package via Composer:

composer require typo3/class-alias-loader

Then, in your application’s bootstrap (e.g., public/index.php, TYPO3’s init.php, or a custom bootstrap script), register the loader before any class usage occurs:

use TYPO3\ClassAliasLoader\ClassAliasLoader;

$aliasLoader = new ClassAliasLoader();
$aliasLoader->register();

// Register aliases early — ideally from a centralized config file
$aliasLoader->addAlias(\My\Legacy\ClassName::class, \My\New\ClassName::class);

First use case: when renaming a class during a refactoring (e.g., My\OldService → My\Service\LegacyService), ensure all callers still work by aliasing the old class to the new one.

Implementation Patterns

• Centralized alias registry: Define all aliases in a dedicated PHP file (e.g., config/class-aliases.php) and include it at bootstrap.

  // config/class-aliases.php
  return [
      \My\Package\OldController::class => \My\Package\Controller\NewController::class,
      \My\Package\DeprecatedInterface::class => \My\Package\ModernInterface::class,
  ];
  

  Then in bootstrap:

  foreach (require 'config/class-aliases.php' as $old => $new) {
      $aliasLoader->addAlias($old, $new);
  }
  

• Integration with TYPO3 extensions: In your extension’s ext_localconf.php, register aliases for internal breaking changes:

  if (class_exists(\TYPO3\ClassAliasLoader\ClassAliasLoader::class)) {
      $aliasLoader = new \TYPO3\ClassAliasLoader\ClassAliasLoader();
      $aliasLoader->addAlias(
          \Vendor\Extension\Utility\OldUtility::class,
          \Vendor\Extension\Utility\NewUtility::class
      );
      $aliasLoader->register();
  }
  

• Version-based conditional aliases: Load different alias sets based on TYPO3 or PHP version:

  if (version_compare(TYPO3_version, '12.0', '<')) {
      $aliasLoader->addAlias(\Old\Class::class, \New\Class::class);
  }
  

• Lazy alias loading: Register aliases lazily via a closure (if using newer versions):

  $aliasLoader->addLazyAlias('OldClass', static fn() => 'NewClass');
  

Gotchas and Tips

• Order matters: Aliases must be registered before any class in the alias chain is referenced. Use early bootstrap points — avoid registering in mid-request controllers.
• No reflection safety: class_alias() doesn’t work with traits, enums, or interfaces the same way; test thoroughly when aliasing non-classes.
• Composer classmap conflict: If you use class_alias() in composer.json scripts (e.g., via ScriptHandler), avoid duplicate registrations. Prefer one source of truth.
• Debugging tip: Track active aliases at runtime:

  $reflection = new ReflectionClass($aliasLoader);
  $property = $reflection->getProperty('aliases');
  $property->setAccessible(true);
  debug($property->getValue($aliasLoader));
  

• Autoloader precedence: This loader does not replace Composer’s autoloader — it simply adds aliases to PHP’s internal registry before the autoloader tries to load classes. Ensure it’s invoked before Composer’s require_once __DIR__ . '/vendor/autoload.php' if possible.
• Clean testing: Use ClassAliasLoader::clearAliases() in test suites ( PHPUnit tearDown()) to avoid cross-test pollution when mocking aliased classes.