Class Alias Loader Laravel Package

Product Decisions This Supports

• Release and deprecation strategy for internal or ecosystem packages: If your team maintains Composer packages consumed by Laravel apps or services, this package supports renaming/moving classes while keeping old class names working for a defined window. A PM can approve a major refactor without forcing every consumer to migrate immediately.
• Build vs buy for backward-compatibility layers: Instead of building custom bootstrap class_alias() glue or maintaining fork patches, adopt a small MIT Composer plugin. Best when the need is narrow: static old→new class mappings.
• Roadmap sequencing for platform modernization: Supports phased namespace/package refactors by decoupling “rename now” from “all consumers migrated now.” Useful in monorepos or shared package sets with staggered upgrade schedules.
• Feature scope decisions: Decide whether to ship an alias map as part of a package release, how long to support old names, and how to document migration. The alias map becomes a concrete inventory of compatibility promises.
• Use cases: maintaining Laravel-first packages with BC guarantees; consuming third-party PHP libraries that already publish alias maps; consolidating namespaces after reorgs or acquisitions; extracting modules from a monolith into packages; keeping legacy integrations alive during upgrades.
• Risk management: Reduces the blast radius of class renames, lowers urgent consumer-side patches, and makes breaking changes more predictable. It does not solve container/facade aliasing, dynamic runtime alias needs, or dependency-injection design issues.

When to Consider This Package

Adopt when:

• You maintain a Composer package/library and need to rename classes while keeping old class names working for at least one release cycle.
• You consume a package that already ships typo3/class-alias-loader alias maps and want those aliases resolved transparently.
• You want a Composer-native solution with minimal application-code changes and are comfortable with composer dump-autoload rewriting vendor/autoload.php.
• Your aliases are static and can live in PHP map files; you do not need dynamic runtime registration as a primary workflow.
• You can accept the operational constraints: Composer plugin execution, vendor mutation, PHP version support, and the package’s small ecosystem footprint.

Look elsewhere when:

• You only need Laravel facade/container aliases (config/app.php, AppServiceProvider, Facade::alias()), not class renames.
• Your project is greenfield or has no renamed classes or third-party alias maps.
• You require case-insensitive class loading (removed in v2; legacy v1.2.2 only).
• Your deployment policy forbids vendor modifications or Composer plugins.
• You need alias usage analytics, automated deprecation enforcement, or dynamic per-request alias behavior.
• You cannot influence the upstream package’s composer.json to add alias maps.
• You are not prepared to maintain alias maps and test both old and new names in CI.

How to Pitch It (Stakeholders)

Executives: This is a small, MIT-licensed Composer plugin that lowers the cost and risk of renaming PHP classes in packages. It lets us ship modernization work without forcing every consumer to upgrade at once, extending compatibility windows and reducing emergency patches. It is not a silver bullet: value is highest if we maintain shared Laravel/PHP packages or depend on libraries that already publish alias maps. Recommend a time-boxed pilot on one package with a real rename, measure consumer upgrade friction, then decide.

Engineering: The plugin hooks into Composer’s autoload dump and lazily registers class_alias() for old class names when requested. Configure alias maps under extra.typo3/class-alias-loader.class-alias-maps; no map means no autoload change. It is Composer-agnostic, not Laravel-specific. Use it for static BC maps in package releases, not as a replacement for Laravel’s service container/facade aliases. Validate with composer dump-autoload, test old and new class names, and pin a known-good version. Note the small ecosystem (44 stars, 0 dependents) and the vendor/autoload.php mutation, so treat it as a targeted compatibility tool rather than a broad platform dependency.