Saferpay Bundle Laravel Package

Getting Started

v2.0.0 is a compatibility release, not a feature release: it moves the package onto Symfony 5.4 (the final 5.x LTS). Practically, that means the package's composer.json constraints on symfony/* were widened or re-pinned to ^5.4, and the major version bump signals that Symfony 4.x is no longer supported. Treat the upgrade as a constraint migration first and a code migration second.

Where to look, in order:

1. composer.json of the package — diff the require block between v1 and v2. The symfony/* pins and any illuminate/* or php bump are the real release notes; the changelog line is a summary.
2. The package's CHANGELOG.md and UPGRADE.md — the release note as published is one sentence, so confirm whether anything beyond constraints changed (removed classes, changed method signatures, dropped container tags).
3. The service provider (src/*ServiceProvider.php) — check whether bindings, singletons, or tagged collections were added, renamed, or removed.
4. config/ — if a config file is publishable, re-publish and diff rather than overwrite.

Minimal upgrade sequence in a consuming Laravel app:

composer why-not vendor/package ^2.0     # see what is holding you back
composer update vendor/package --with-all-dependencies -W
php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" --tag=config --force
php artisan config:clear && php artisan cache:clear
php artisan test

First real use case: pick the single hot path that touches the package (a console command, an HTTP client call, a formatter) and verify it end-to-end on Symfony 5.4 before rolling the upgrade across the app. The most common failure mode here is not the package's own code — it's a transitive Symfony component resolving to a version the package no longer tolerates.

Implementation Patterns

Pin the pair, not the package. Laravel and this package share the Symfony constraint graph. Upgrade Laravel and the package in the same PR, then run composer update --with-all-dependencies. Splitting them across two deploys produces resolver conflicts that are hard to attribute.

Depend on the package's contracts, not on Symfony's classes. If your application code type-hints Symfony\Component\... classes directly because the package happened to expose them, a future Symfony 6 bump becomes your problem. Wrap the package behind your own interface or a thin adapter class, and let the container bind it:

$this->app->bind(MyWrapper::class, fn ($app) => new MyWrapper($app->make(Vendor\Package\Client::class)));

Test against the constraint floor and ceiling. Add a CI matrix job at --prefer-lowest alongside the default resolution. Symfony 5.4 compatibility bugs almost always surface on the lowest allowed patch version, never on the latest.

Use the package's test doubles where offered. If the release added Symfony 5.4-era fakes (clock, HTTP client, process), prefer them over hand-rolled mocks — they track signature changes for you across future bumps.

If you maintain a downstream package, widen rather than bump: "vendor/package": "^1.0 || ^2.0" where the API is unchanged, and gate any behavior difference behind a runtime check rather than a hard version switch.

Gotchas and Tips

• The -W flag is not optional. composer update vendor/package alone will frequently leave a transitive symfony/console or psr/container at an incompatible version. --with-all-dependencies is the difference between a clean resolve and an hour of debugging.
• psr/container 1.x vs 2.x is the classic collision on this upgrade path. If a third-party package pins ^1.0, you cannot reach the Symfony 5.4 line until that dependency moves. Check with composer depends psr/container.
• Deprecations are the signal, not the noise. Symfony 5.4 emits deprecations for everything removed in 6.0. Turn on symfony/deprecation-contracts logging (SYMFONY_DEPRECATIONS_HELPER=weak in dev) and actually read the output — that list is your Symfony 6 upgrade ticket.
• config:cache will mask config changes. After re-publishing config, always php artisan config:clear. A stale cached config is the most common "the upgrade broke my settings" false alarm.
• A major bump can silently drop supported PHP versions. Confirm the new php constraint against every environment, including CI images and the production runtime — this bites late and hard.
• Debugging resolver failures: use composer why-not vendor/package 2.0.0 (which package blocks the target) and composer prohibits symfony/console 5.4.*. Reading the solver's complaint directly is faster than guessing at constraints.
• Extension points worth knowing: container tags and macroable traits usually survive a compatibility bump untouched, but anything bound as a singleton with a Symfony type in its constructor may need rebinding if the signature shifted. Grep your AppServiceProvider for the package namespace after upgrading.
• Plan the exit, not just the entry. Symfony 5.4 is an LTS on a fixed end-of-life clock. v2.0.0 buys runway, not permanence — file a ticket now for the package's Symfony 6.x path so this doesn't become urgent later.