Symfony Routing Auto Loader Bundle Laravel Package

Getting Started

Heads-up before you composer require: this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/*.php publish tag, and no auto-discovery via Laravel's package manifest. Installing it in a Laravel app does nothing — Laravel's router does not read Symfony route loaders. Treat this assessment as (a) relevant only if you maintain a Symfony service alongside Laravel apps, or (b) a reference for how attribute-based route auto-loading is designed, so you can pick the Laravel-native equivalent.

1. Install and register (Symfony side only): composer require tourze/symfony-routing-auto-loader-bundle, then add the bundle to config/bundles.php. Verify with bin/console debug:router that it boots before writing any routes.
2. Where to look first: the bundle's Attribute/ (or Annotation/) namespace for the route attributes, then the DependencyInjection/ extension and any compiler pass that collects controllers. That compiler pass is where the "auto" magic lives — read it before debugging anything.
3. First use case: annotate a controller class or action with the bundle's route attribute instead of hand-writing routes.yaml, then confirm the route appears in debug:router.

If you're actually on Laravel: skip this package. Use Laravel 11's bootstrap/app.php → withRouting(...) for file-based config, or spatie/laravel-route-attributes if you want attribute-driven discovery. Both give you the same ergonomics with first-class framework support.

Implementation Patterns

• Convention over configuration: keep controllers in the scanned directory (typically src/Controller/) and let the attribute supply path, name, and methods. Anything outside the scan path is invisible — see Gotchas.

• Name routes explicitly in the attribute. Auto-generated names are the most common source of route() failures and collisions; setting name: gives you a stable contract for $urlGenerator->generate() and Twig/Blade-style helpers.

• Prefix and version by attribute argument, not by duplicating paths. Group multiple controllers under one prefix so a version bump is a single-file change rather than an N-file sweep.

• Parity map for Laravel devs reading Symfony code:

  Laravel	Here
  Route::get(...)	route attribute on the action
  ->name('posts.show')	attribute name argument
  ->middleware('auth')	firewall + access_control in security.yaml
  ->prefix('api/v1')	attribute prefix / bundle config
  php artisan route:list	bin/console debug:router
  php artisan route:cache	bin/console cache:warmup / router cache

• Integration tip: after adding or renaming an attribute, always clear the router cache in the same deploy step. In CI, add a debug:router smoke check so a silently-unregistered controller fails the build instead of 404ing in production.

• Extension point: if the scan paths or naming rules don't fit, the bundle config (extension class) is the intended override surface — prefer that over forking, since 1.0.0 signals a stabilised API you'll want to stay on.

Gotchas and Tips

• 1.0.0 is the first stable release, and the release notes contain only a diff link. No changelog prose, no BC-break list. Before upgrading from 0.0.2, actually read the compare diff (0.0.2...1.0.0) — a 0.0.x → 1.0.0 jump frequently bundles renames of attribute classes or config keys that SemVer permits precisely because 0.0.x carried no stability promise. Pin ^1.0 going forward, but treat this specific upgrade as a potential breaking change until proven otherwise.
• Silent non-discovery is the #1 failure mode. Controllers outside the configured scan directory, abstract/parent classes, and non-public methods are skipped without error. Symptom: a route that "should" exist 404s while debug:router shows nothing and no exception is thrown.
• Route-name collisions from auto-generated names surface late — often as the wrong URL rendering in a template rather than as an exception. Set names explicitly.
• Cache staleness: attribute changes are not picked up until the router/container cache is rebuilt. If your local change "doesn't work," clear the cache before debugging the bundle.
• Debugging commands: bin/console debug:router --show-controllers to confirm which controller produced which route; bin/console router:match /path to test a single URL against the matcher.
• Don't force this into Laravel. There is no adapter layer, and wiring Symfony's routing component into Laravel's router means fighting two containers and two caches. Reach for the Laravel-native packages named above instead.
• No prior assessment exists, and this release ships no prose notes — so the practical stance is: adopt only with the diff reviewed, and keep the bundle's own tests (or a small route-count assertion) in your CI as the regression net the changelog doesn't provide.