Service Alias Autoregister Bundle Laravel Package

Getting Started

• Install with composer require loophp/service-alias-autoregister-bundle. Despite the "Laravel developer" framing, this is a Symfony bundle — it hooks into Symfony's DI container via a compiler pass. In Laravel you'd only benefit from it if you're running Symfony's DI component inside your app (rare); the day-to-day Laravel equivalent is $this->app->bind(Interface::class, Impl::class) in a service provider.
• Where to look first: composer.json (PHP constraint and Symfony version range), the bundle's DependencyInjection/Configuration.php for the exact config keys, and the compiler pass class — that's where the aliasing logic lives.
• Register the bundle in config/bundles.php (Symfony) and, if you insist on using it under Laravel, wire it through a small service provider that boots the bundle's container extension against a Symfony ContainerBuilder — do not expect Laravel's container to be touched.
• First use case: define class FileLogger implements LoggerInterface, let it be autoconfigured, and the bundle creates LoggerInterface → FileLogger aliases for you, so public function __construct(LoggerInterface $logger) autowires without any manual services.yaml alias entry.
• Before writing code, read the README's configuration block verbatim. The whole value proposition is a handful of config keys (include/exclude patterns, whether to alias interfaces, parents, or both), and guessing them wastes more time than reading them.
• Sanity check after install: run bin/console debug:container --show-private and confirm the aliases you expected appear. If they don't, nothing downstream will work.

Implementation Patterns

• Interface-first services. Write services against narrow interfaces, register the concrete class as usual, and let the bundle produce the Interface → Implementation alias. This keeps services.yaml free of alias boilerplate as the codebase grows.
• Exclude the noise. Vendor services, Doctrine repositories, and abstract base classes all implement interfaces and will happily get aliased. Use exclusion patterns aggressively (namespace prefixes are the cleanest lever) and treat the default behaviour as "alias everything" rather than "alias only what I meant."
• One implementation per interface. The pattern only stays predictable when there's a single concrete class per interface per container. As soon as two ship, you're relying on registration order — see Gotchas.
• Decorators and test doubles. Because aliases are generated, swapping an implementation in a test container is a matter of registering your fake as the interface's target rather than editing YAML. Combine with test.service_container in Symfony so aliases stay visible to the test container.
• Package authors. This bundle shines when you ship a library with many small interfaces and don't want consumers writing alias config. Document which interfaces are intended for autowiring and which are internal.
• Laravel-side integration tip. If you use this in a shared library but consume it from Laravel, mirror the contracts in a ServiceProvider with explicit bind() calls. Duplicating the mapping in two places is annoying but far cheaper than trying to run a Symfony compiler pass inside Laravel's container.
• CI/CD flow. Aliases are compiled into the container cache. In deploy scripts, always run a cache warmup (cache:clear / cache:warmup) as part of the release, not just composer install — otherwise a stale container silently serves the old alias map.

Gotchas and Tips

• Multiple implementers = undefined winner. If two services implement the same interface, the resulting alias depends on compiler pass ordering, not on anything you wrote. Debug with debug:container <Interface> and be explicit when ambiguity is intentional.
• Private and synthetic services. Aliases only make sense for services that are actually in the container and reachable. A private service behind an alias still needs to be referenced (or made public) to be injected in some contexts.
• Nothing happens at runtime. The bundle does its work at compile time. If an alias is missing, the fix is in configuration or registration order — not in your consuming class. Clear the cache before concluding anything.
• Debugging checklist: bin/console debug:autowiring to see what the container thinks it can inject, debug:container --deprecations, and lint:container to catch alias-to-abstract-class mismatches.
• This release (1.0.1) is CI-only. Every merged PR is a chore(deps) bump (actions/stale, setup-php, actions/cache, actions/checkout, Renovate config) plus commits labelled ci:, cs:, tests:. There is no functional change, no new config key, no deprecation. Upgrading is low risk.
• But verify the PHP floor. The refactor: modernize code and refactor: switch to phpunit 10 commits occasionally ride along with a minimum-PHP bump in composer.json. PHPUnit 10 implies PHP 8.1+ for the test suite; confirm the library's own require.php before rolling this onto an older runtime.
• Extension points are thin by design. There's no event or plugin hook to customise alias naming per-service beyond config patterns; if you need finer control, write your own compiler pass and disable the overlapping config here rather than fighting it.
• Ecosystem drift caveat. The bundle's Symfony version support is set by its CI matrix, which was just modernised. If you're on an older Symfony LTS, check the constraint range in composer.json — the passing CI on this release may not exercise your version.