Class Alias Loader Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require typo3/class-alias-loader
   

2. Configure composer.json: Add your alias map file path under extra:

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

3. Create an Alias Map File (e.g., app/Compatibility/LaravelAliasMap.php):

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

4. Dump Autoload:

   composer dump-autoload
   

5. Test: Verify deprecated class usage works without errors (e.g., new Old\Deprecated\Class()).

First Use Case

Laravel Facade Migration: Replace Input::old() with request()->old() gradually by adding:

return [
    'Illuminate\Support\Facades\Input' => 'Illuminate\Http\Request',
];

Now Input::old() transparently resolves to Request::old().

Implementation Patterns

Workflows

1. Phased Migration:

   • Add aliases for deprecated classes in composer.json.
   • Test legacy code paths (e.g., admin panels, APIs) without modifying business logic.
   • Gradually replace usages in new features, removing aliases once confidence grows.

2. Third-Party Compatibility:

   • For libraries like Symfony or Doctrine, create a vendor-specific alias map (e.g., vendor/symfony/alias-map.php).
   • Example:

     return [
         'Symfony\Component\Debug\Debug' => 'Symfony\Component\Debug\Debugger',
     ];
     

3. Dynamic Aliases (Runtime):

   • Enable always-add-alias-loader in composer.json:

     "extra": {
         "typo3/class-alias-loader": {
             "always-add-alias-loader": true
         }
     }
     

   • Add aliases programmatically (e.g., in a service provider):

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

4. API-Driven Resolution:

   • Use ClassAliasMap::getClassNameForAlias() in custom logic:

     $newClass = \TYPO3\ClassAliasLoader\ClassAliasMap::getClassNameForAlias('Old\Class');
     if ($newClass !== 'Old\Class') {
         // Handle migration logic
     }
     

Integration Tips

• Laravel Facades: Avoid aliasing Facades directly (breaks DI). Use AppServiceProvider:

  Facade::alias('Input', Request::class);
  

  Reserve the loader for non-Facade classes (e.g., helpers, models).

• Monorepos: Place alias maps in a shared config/ directory (e.g., config/compatibility/laravel.php).

• CI/CD: Add composer dump-autoload to your build pipeline to ensure aliases are always up-to-date.

• Testing: Mock aliases in tests using ClassAliasMap::addAliasMap() to simulate deprecated behavior.

Gotchas and Tips

Pitfalls

1. Facades and Dependency Injection:

   • Issue: Aliasing Facades (e.g., Input) breaks Laravel’s container binding.
   • Fix: Use Facade::alias() in AppServiceProvider instead.

2. Namespace Collisions:

   • Issue: Ambiguous aliases (e.g., Old\Class vs. Old\Other\Class) may cause ClassNotFound errors.
   • Fix: Use fully qualified names in alias maps (e.g., \App\Old\Class).

3. Autoload Conflicts:

   • Issue: Corrupted vendor/autoload.php if the loader fails silently.
   • Fix:
     • Backup vendor/autoload.php before running composer dump-autoload.
     • Test in a staging environment first.

4. Case Sensitivity:

   • Issue: PHP 8+ enforces case-sensitive autoloading. Aliases must match exactly.
   • Fix: Use strtolower() or strtoupper() in alias maps if case-insensitive behavior is needed (not recommended post-v2.0.0).

5. Performance Overhead:

   • Issue: Static alias maps (v2.0+) improve OPCache performance, but dynamic maps add runtime checks.
   • Fix: Prefer static maps in composer.json for production.

6. Composer Plugin Conflicts:

   • Issue: Other Composer plugins (e.g., humbug/phar-updater) may interfere with autoload generation.
   • Fix: Test with --no-plugins to isolate the issue:

     composer dump-autoload --no-plugins
     

Debugging Tips

1. Inspect Aliases: Create a custom Artisan command to list active aliases:

   // app/Console/Commands/ListAliases.php
   use TYPO3\ClassAliasLoader\ClassAliasMap;
   public function handle() {
       $aliases = ClassAliasMap::getAllAliasMaps();
       dd($aliases);
   }
   

   Run with:

   php artisan alias:list
   

2. Check Autoload: Verify vendor/autoload.php includes the loader:

   grep -A5 "ClassAliasLoader" vendor/autoload.php
   

3. Enable Debugging: Set TYPO3_CLASS_ALIAS_LOADER_DEBUG=1 in your environment to log alias resolutions.

4. Common Errors:

   • "Class not found":
     • Ensure the new class exists and the alias map is correct.
     • Run composer dump-autoload --optimize.
   • Facade errors:
     • Check if the class is a Facade (use Facade::alias() instead).

Extension Points

1. Custom Alias Maps:

   • Extend by adding more maps in composer.json or dynamically via ClassAliasMap::addAliasMap().

2. Preventive Aliasing:

   • Use the API to block deprecated usage:

     $oldClass = 'Old\Class';
     $newClass = ClassAliasMap::getClassNameForAlias($oldClass);
     if ($newClass !== $oldClass) {
         Log::warning("Deprecated class used: {$oldClass}");
     }
     

3. Environment-Specific Aliases:

   • Load different maps per environment (e.g., alias-map.prod.php, alias-map.dev.php) using always-add-alias-loader.

4. Integration with Laravel:

   • Hook into booted event to add runtime aliases:

     use Illuminate\Foundation\Application;
     Application::booted(function () {
         ClassAliasMap::addAliasMap([
             'Legacy\Class' => 'App\\Legacy\\NewClass',
         ]);
     });