Weave Code
Class Alias Loader Laravel Package
typo3/class-alias-loader
Composer plugin that adds a class alias autoloader for backward compatibility when libraries rename classes. Packages provide PHP alias map files; on autoload dump it amends vendor/autoload.php and transparently class_alias() old names to new ones.
Composer Plugin to provide aliases to PHP classes that have been renamed
Frequently asked questions about Class Alias Loader
- How can I use this package to maintain backward compatibility for Laravel Facades like Input or Cache during a major upgrade?
- Add a custom alias map file (e.g., `app/ClassAliasMap.php`) returning an associative array of old-to-new class names, then reference it in your `composer.json` under `extra.typo3/class-alias-loader.class-alias-maps`. Run `composer dump-autoload` to generate the autoload.php with aliases. For Facades, combine this with `AppServiceProvider` bindings for container-level compatibility.
- Does this package work with Laravel’s Facade system (e.g., Facade::alias()) or only static classes?
- The package handles static class aliases transparently via `class_alias()`. For Facades, you’ll need to pair it with Laravel’s `Facade::alias()` in an `AppServiceProvider` or create a custom Facade class that delegates to the alias loader’s API (`ClassAliasMap::getClassNameForAlias`). It doesn’t replace Facade-specific logic but complements it.
- What Laravel versions are officially supported, and are there any breaking changes between v1.x and v2.x?
- The package is framework-agnostic and works with any Laravel version using PHP 7.4+. Version 2.0.0+ enforces case-sensitive aliases (fixing a common issue in TYPO3 ecosystems) and requires PHP 8.1+. Downgrade to v1.2.2 if you need case-insensitive loading or PHP <8.1 support. Always pin to a specific minor version in `composer.json` for stability.
- How do I test my Laravel app with deprecated class names still in use during a migration?
- Include the alias loader in your test environment by running `composer dump-autoload` before tests. The package preserves deprecated code paths, so tests using old class names (e.g., `Input::old()`) will resolve correctly. For Pest/PHPUnit, ensure your alias maps are loaded in `phpunit.xml` or `pest.php` via the same `composer.json` configuration as production.
- Can I use this for third-party libraries (e.g., Symfony components or Doctrine entities) in a Laravel app?
- Yes. If a third-party package provides its own alias map (e.g., `vendor/symfony/alias-map.php`), the loader will automatically pick it up. For libraries without maps, create a custom map file in your project and reference it in `composer.json`. This is ideal for monorepos or apps mixing Laravel with Symfony/Doctrine where shared dependencies need backward compatibility.
- Will this package slow down my Laravel application in production, especially for high-traffic APIs?
- No. The loader adds **zero overhead** when no aliases are used (default behavior). When active, it uses static alias maps (v2.0.0+) and `class_alias()`, which are opcache-friendly and benchmark at **<1ms latency**. For CLI-heavy workflows or APIs, this is negligible compared to database or HTTP overhead. Always test with `opcache.enable=1` in your PHP config.
- How do I handle environment-specific aliases (e.g., staging vs. production) without hardcoding them in composer.json?
- Use the loader’s dynamic map API. Instead of static `composer.json` maps, call `ClassAliasMap::addAliasMap()` in your `bootstrap/app.php` or a service provider, loading environment-specific maps (e.g., `config/aliases/staging.php`). This avoids CI/CD conflicts and lets you toggle aliases per environment without redeploying.
- What if I’m using Docker or a CI system where vendor/ is read-only? Can I still use this package?
- Yes. Use the `always-add-alias-loader` flag in `composer.json` to force the loader to register even without maps, then dynamically add aliases at runtime via `ClassAliasMap::addAliasMap()`. This bypasses the need to modify `vendor/autoload.php` and works in read-only environments. Example: `composer require typo3/class-alias-loader --always-add-alias-loader`.
- Are there alternatives to this package for Laravel-specific backward compatibility (e.g., Facades or helpers like str_limit)?
- For Laravel Facades, consider `laravel-shift/blueprint` (for Facade migrations) or `spatie/laravel-facade-decorator`. For static helpers (e.g., `str_limit`, `e()`), this package is more lightweight. If you need **both** Facade and class alias support, combine it with `Facade::alias()` in an `AppServiceProvider`. Avoid reinventing the wheel—this loader focuses on **class-level** backward compatibility, not container bindings.
- How do I debug why a deprecated class isn’t being aliased in my Laravel app?
- First, verify your alias map is loaded by running `composer why-not <old-class-name>`. If the map is missing, check your `composer.json` `extra` section. For runtime issues, enable debug logging by calling `ClassAliasMap::setDebug(true)` and check Laravel’s logs for `class_alias()` resolutions. Use `composer dump-autoload --optimize` to regenerate autoload files if maps aren’t being picked up.
Weaver
How can I help you explore Laravel packages today?