Class Alias Loader Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require typo3/class-alias-loader
   

   Add to your root composer.json under extra:

   "extra": {
       "typo3/class-alias-loader": {
           "class-alias-maps": [
               "path/to/YourAliasMap.php"
           ]
       }
   }
   

2. Create an Alias Map: Define a PHP file (e.g., app/Compatibility/LaravelAliasMap.php) returning an associative array:

   return [
       'Old\Deprecated\Class' => 'App\\New\\Class',
       'Illuminate\Support\Facades\Input' => 'Illuminate\Http\Request',
   ];
   

3. Trigger Autoload Update:

   composer dump-autoload
   

   The package hooks into Composer’s autoloader and injects class_alias() calls for old class names.

4. Verify: Test by requiring an old class name:

   $oldClass = new Old\Deprecated\Class(); // Transparently loads App\New\Class
   

First Use Case

Laravel Facade Migration: Replace deprecated Laravel 8 Facades (e.g., Input, Cache) with their Laravel 11 equivalents without rewriting legacy code:

// composer.json
"extra": {
    "typo3/class-alias-loader": {
        "class-alias-maps": ["app/Compatibility/LaravelFacades.php"]
    }
}

// app/Compatibility/LaravelFacades.php
return [
    'Illuminate\Support\Facades\Input' => 'Illuminate\Http\RequestFacade',
    'Illuminate\Support\Facades\Cache' => 'Illuminate\Cache\Facades\Cache',
];

Implementation Patterns

Core Workflows

1. Static Alias Resolution (Recommended)

   • Define all aliases in composer.json and let the loader handle them during composer dump-autoload.
   • Best for: Long-term compatibility layers (e.g., Laravel version upgrades, third-party library migrations).
   • Example:

     "extra": {
         "typo3/class-alias-loader": {
             "class-alias-maps": [
                 "vendor/package/alias-map.php",
                 "app/Compatibility/CustomAliases.php"
             ]
         }
     }
     

2. Dynamic Runtime Aliases

   • Use always-add-alias-loader: true to ensure the loader runs even without maps.
   • Add aliases programmatically via the API:

     use TYPO3\ClassAliasLoader\ClassAliasMap;
     
     ClassAliasMap::addClassAliasMap([
         'Dynamic\OldClass' => 'App\\Dynamic\\NewClass',
     ]);
     

   • Best for: Environment-specific configs (e.g., staging vs. production aliases).

3. API-Driven Resolution

   • Use ClassAliasMap::getClassNameForAlias() to resolve aliases in strings (e.g., configuration, logs):

     $newClass = ClassAliasMap::getClassNameForAlias('Old\Class');
     if ($newClass !== 'Old\Class') {
         // Use $newClass instead
     }
     

   • Best for: Legacy code audits, dynamic class instantiation, or serialization.

4. Third-Party Library Integration

   • Distribute alias maps with your package by including them in composer.json:

     "extra": {
         "typo3/class-alias-loader": {
             "class-alias-maps": ["vendor/your-package/aliases.php"]
         }
     }
     

   • Best for: Libraries needing to support old class names (e.g., tx_* → TYPO3\CMS\*).

Integration Tips

• Laravel-Specific:

  • Combine with Laravel’s AppServiceProvider for Facade overrides:

    public function register()
    {
        if (class_exists('Old\Facade\Class')) {
            \Facade\IgnoreFacadeRerebinding::ignore('Old\Facade\Class');
            \Facade\Facade::alias('Old\Facade\Class', 'App\\New\\Facade');
        }
    }
    

  • Use the loader for non-Facade classes (e.g., Old\Helper\Functions → App\Helpers\Utils).

• Performance:

  • Opcache-friendly: Static alias maps in v2.0+ reduce runtime overhead.
  • Avoid overloading with too many aliases; prefer targeted maps (e.g., one per major dependency).

• Testing:

  • Mock class_alias() in PHPUnit to test alias behavior:

    $this->getMockBuilder('TYPO3\ClassAliasLoader\ClassAliasLoader')
         ->disableOriginalConstructor()
         ->onlyMethods(['register'])
         ->getMock();
    

• CI/CD:

  • Run composer dump-autoload in your pipeline to ensure aliases are up-to-date.
  • Use always-add-alias-loader: true to catch missing maps early.

Gotchas and Tips

Pitfalls

1. Autoload Conflicts:

   • Issue: The loader modifies vendor/autoload.php. If your project uses custom autoloaders (e.g., autoload_dev.php), conflicts may arise.
   • Fix: Ensure the loader runs after Composer’s default autoloader. Check for errors in composer dump-autoload --verbose.

2. Case Sensitivity:

   • Issue: v2.0+ enforces case-sensitive class names. If your code uses old\class vs. Old\Class, aliases won’t resolve.
   • Fix: Use v1.2.2 for case-insensitive support or standardize class names in your alias maps.

3. Facade Breakage:

   • Issue: Static aliases do not work with Laravel Facades unless explicitly rebound in AppServiceProvider. Example:

     // ❌ Won’t work:
     $input = new Illuminate\Support\Facades\Input; // Uses alias, but Facade::swap() is bypassed.
     
     // ✅ Workaround:
     \Facade\Facade::alias('Input', 'Illuminate\Http\RequestFacade');
     

   • Fix: Use Laravel’s Facade::alias() for Facades; reserve the loader for non-Facade classes.

4. Circular Dependencies:

   • Issue: Aliases that reference each other (e.g., A => B, B => A) cause infinite loops.
   • Fix: Validate maps with:

     $map = require 'path/to/alias-map.php';
     $this->assertNoCircularReferences($map);
     

5. Opcache Invalidation:

   • Issue: Changing alias maps requires Opcache restart to take effect.
   • Fix: Clear Opcache or use opcache_reset() in your deployment script.

6. PHP Version Mismatch:

   • Issue: v2.0+ drops PHP < 8.1 support. If you’re on PHP 8.0 or lower, use v1.2.2.
   • Fix: Pin the version in composer.json:

     "require": {
         "typo3/class-alias-loader": "1.2.2"
     }
     

7. Composer Plugin Conflicts:

   • Issue: Other Composer plugins (e.g., composer/pcre) may interfere with autoload generation.
   • Fix: Run composer diagnose to check for conflicts. Isolate the loader by testing in a clean vendor/ directory.

Debugging Tips

1. Verify Alias Injection:

   • Check vendor/autoload.php for class_alias() calls after composer dump-autoload.
   • Search for:

     class_alias(\Old\Class::class, \New\Class::class, true);
     

2. Log Missing Aliases:

   • Override the loader’s register() method to log unresolved classes:

     \TYPO3\ClassAliasLoader\ClassAliasLoader::register();
     // Add logging before/after registration.
     

3. Test Alias Resolution:

   • Use a helper function to debug:

     function debugAlias(string $class): void
     {
         if (class_alias($class, $class, true)) {
             echo "Alias for {$class} exists.\n";
         } else {
             echo "No alias found for {$class}.\n";
         }
     }
     

4. Check for Duplicates:

   • Duplicate aliases (e.g., A => B and A => C) cause class_alias() to fail silently.
   • Validate maps with:

     $map = require 'path/to/alias-map.php';
     $this->assertCount(count(array_unique($map)), $map);
     

Extension Points

1. Custom Loader Initialization:
   • Extend the loader’s behavior by subclassing TYPO3\ClassAliasLoader\ClassAliasLoader:

     class CustomAliasLoader extends \TYPO3\ClassAliasLoader\ClassAliasLoader
     {
         public