Union Bundle Laravel Package

Getting Started

v1.1.0 is a dependency-floor release: the package now requires Symfony 7 components. That single line has more consequences than the changelog suggests, so treat the upgrade as a platform decision rather than a patch bump.

Before anything else, confirm you can actually install it:

php -v                                   # must be >= 8.2
composer why-not symfony/console ^7.0    # usually names Laravel as the blocker

Symfony 7 requires PHP 8.2+, and Laravel 10 pins Symfony 6.x — so in practice v1.1.0 means Laravel 11+. If you are still on Laravel 10, stay on the previous package release and plan the framework upgrade first.

Where to look first, in order:

1. The package's composer.json — read both require and conflict. The require block is the real documentation for this release.
2. config/<package>.php after php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider".
3. The package service provider's register() method — that is where interfaces are bound to drivers, and where you will later override behaviour.
4. The manager/factory class everything funnels through.

First use case: resolve the package's contract out of the container rather than instantiating anything yourself.

public function __construct(private PackageContract $package) {}

If the container resolves it cleanly, the Symfony 7 swap worked. If it throws an Unresolvable dependency or an argument-count error, you are looking at a stale binding or a cached config — php artisan optimize:clear before debugging further.

Implementation Patterns

Depend on the contract, not the driver. The package's value is that config selects a driver; type-hint the interface in your own classes so a driver change is a config change. Every place you import a concrete Symfony class directly is a place the next major bump can break.

Isolate the upgrade surface behind a thin adapter. Symfony major releases routinely change constructor argument order on things like ObjectNormalizer and ValidatorBuilder. If the package is the only thing that touches those classes, the next bump is a one-line composer update. Wrap it:

final class DocumentValidator
{
    public function __construct(private PackageContract $package) {}

    public function validate(Document $doc): Result
    {
        return $this->package->validate($doc);
    }
}

Then your tests assert on DocumentValidator, not on Symfony internals.

Config per environment, driver per job. Anything that shells out, talks to a browser, or sends mail should have its driver chosen in config/<package>.php from env, so CI and production can diverge without code changes.

Queue jobs must re-resolve, never serialize. Component objects are not reliably serializable and Symfony 7 tightened several of them. Pass IDs or scalars through the constructor and resolve the service inside handle().

Testing. Swap the binding for a fake in a test service provider or use $this->mock(PackageContract::class); the package is designed to be replaced at the container boundary. Keep one or two integration tests that hit the real driver so an upgrade that silently changes behaviour gets caught.

Upgrade workflow that actually works: branch → bump the package → composer update --with-all-dependencies → run the full suite → check the deprecation log, not just the failures. Passing tests hide deprecations that become errors in the next major.

Octane. If the underlying driver holds per-request state, register the binding as scoped in your own provider rather than singleton.

Gotchas and Tips

Symfony 7 removed every deprecation from 6.4. The big one for Laravel developers is annotation-based configuration: @Assert\* in the Validator, @Route in Routing, @Groups/@SerializedName in the Serializer. Attributes only now. Grep for Doctrine\Common\Annotations and @Assert across your app — the package upgrade will surface these as runtime failures, not compile errors.

ContainerAwareInterface and ContainerAwareTrait are gone. Any custom class of yours that received the container via setContainer() breaks. Inject explicitly.

Constructor signatures shifted on hand-built Symfony services. If you construct ObjectNormalizer, ValidatorBuilder, or similar outside the package, expect argument-order and required-argument errors. Prefer the package's factory, or move to named arguments.

The Laravel 10 conflict is the most common failure. Error text looks like vendor/package requires symfony/console ^7.0 -> found symfony/console[v6.4.x] but it is fixed by laravel/framework. Don't fight it with --ignore-platform-reqs; resolve the framework version.

Clock and time-sensitive tests. Symfony 7's components route sleep() through symfony/clock. Tests that relied on real sleeps or on mocking time() need ClockMock or Carbon::setTestNow().

Debugging resolution problems:

composer show --tree vendor/package
php artisan about                 # confirms framework + PHP actually in play
php artisan tinker --execute="dump(app(PackageContract::class));"

Deprecation noise. Set SYMFONY_DEPRECATIONS_HELPER=disabled in CI only if you have a separate deprecation-reporting job — otherwise you lose the early warning that makes the next major bump cheap.

Extension point. The cleanest way to customise behaviour is to bind your own implementation of the package contract in a service provider registered after the package's, or to add a driver via the package's extension hook if it exposes one. Subclassing the manager is a last resort — it re-couples you to Symfony internals and undoes the whole point of this release.