Routing Auto Bundle Laravel Package

Getting Started

This release raises the floor on the runtime: PHP 5.6/7.0 and Symfony 3.0–3.2 are gone, and Symfony 4 is now supported. Before you write any feature code, spend five minutes on the compatibility triangle — your PHP version, your Laravel version's Symfony constraint, and this package's constraint.

1. Read composer.json first, not the README. Confirm the actual constraint shape (^3.3|^4.0 vs ^4.0 only) and the php requirement. That tells you whether 2.1.0 is a drop-in or a forced Laravel upgrade.
2. Check what your app already pins. composer why symfony/console (and symfony/http-foundation, symfony/event-dispatcher, symfony/process). Laravel 5.5 and earlier pin Symfony 3.x, so they cannot resolve this release — you'll need Laravel 5.6+ (PHP 7.1.3+) or you stay on 2.0.x.
3. Upgrade in a branch, with the lock file committed. composer require vendor/package:^2.1 --with-all-dependencies, then diff composer.lock and look for unexpected Symfony minor jumps across other packages.
4. First use case: one end-to-end happy path in a test. Don't smoke-test in the browser. Write a single feature test that exercises the package's primary flow through the container, run it, and only then wire it into controllers/jobs.

Look first at, in this order: CHANGELOG/UPGRADE if present, the service provider (what it binds and auto-discovers), the published config file, then the source of whichever class you plan to call.

Implementation Patterns

Resolve, don't instantiate. Pull the package's entry class out of the container (app(Manager::class), constructor injection, or a Facade only at the edges). The 2.1.0 bump is a reminder that the package's constructor signatures can move with Symfony; anything you new yourself becomes your migration debt.

Keep Symfony at arm's length. If you extend package classes that inherit from Symfony components (Console commands, Mailable-adjacent transports, HTTP clients), treat those subclasses as the blast radius of the next major. Wrap the package behind a small application-level interface (App\Support\X\Gateway) so a future ^3.0 or Symfony 5 bump touches one adapter, not thirty call sites.

Config-driven, environment-overridden. Publish the config, keep defaults in config/, and override per-environment via .env. Anything the package exposes as a driver/manager should be selected by config key rather than by branching in your own code.

CI matrix, lowest deps included. With a Symfony 4 support window, test at minimum: PHP 7.1, 7.2, 7.3; your lowest and highest supported Laravel; and one composer update --prefer-lowest job. --prefer-lowest is what catches "works only because my local lock happened to have symfony/console 4.4".

Test against the package, not around it. Use Laravel's container and testing helpers so the service provider, config merging, and facades are all exercised. Mock external I/O at the boundary the package defines (its client/transport interface), not by mocking its internals.

Upgrade choreography. For existing 2.0.x installs: bump PHP in CI and platform.php in composer.json config first, ship that, then bump the package. Two separate PRs, two separate failures if something goes wrong.

Gotchas and Tips

• EOL PHP is a hard pin, not a warning. If you're on 7.0, composer require will either fail or silently resolve you to 2.0.x. Pin explicitly ("vendor/package": "^2.0") so you get a clear error instead of a confusing downgrade.
• Transitive Symfony conflicts are the real upgrade cost. The package supporting Symfony 4 doesn't mean your dependency tree can use it. composer why-not symfony/console 4.0 is the fastest diagnostic when resolution fails.
• Symfony 4 removed a lot of long-deprecated surface. If you call or override package methods that pass through to Symfony (event dispatch by name, Container::get signatures, console helpers), expect removals rather than deprecation notices. Static analysis (phpstan/psalm at level ~5 against vendor/) will find these faster than tests will.
• Config caching hides config changes. After upgrading, php artisan config:clear (and route:clear, view:clear) before concluding the package is broken. In production deploys, config:cache runs in a different order than you think.
• Restart long-lived workers after the upgrade. Queue workers and Octane/Swoole processes hold old class definitions; queue:restart is not optional.
• Extension points to check before you fork anything: publishable config, container bindings in the provider, and any extend()/driver() hooks. Most "I need to change one behaviour" cases are a binding override, not a fork — and a fork is what makes the next Symfony bump painful.
• Debugging order for weird failures post-upgrade: composer dump-autoload → config:clear → check for a duplicated service provider registration (auto-discovery plus a manual providers entry is a classic double-bind) → only then read the stack trace.
• Compatibility is a two-sided constraint. If you maintain downstream packages that depend on this one, widen your own constraint to ^2.0|^2.1 before the upgrade lands, otherwise you've just broken your own users.