Symfony Breadcrumbs Bundle Laravel Package

Getting Started

This release (7.0.0) is a platform-requirements release: the headline change is a raised PHP floor and refreshed Symfony dependency constraints. There are no new end-user features to learn, so "getting started" here is really about getting your environment and lockfile into a state where the package can install at all.

1. Check the floor before anything else. Open the package's composer.json and read require.php and the symfony/* entries. Compare against your application's composer.json platform config and your CI matrix (including any setup-php / Docker base images). If you are still on the previous PHP minor, this upgrade is blocked at the resolver level — not at runtime — so you will find out immediately.
2. Install and read the diff. composer require <vendor>/<package>:^7.0 --with-all-dependencies. The --with-all-dependencies flag matters: the Symfony constraint refresh will often force transitive upgrades (symfony/console, symfony/http-foundation, symfony/process) that a plain composer update will refuse to move.
3. Look first at the service provider and config file, not the README. Run php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider" and diff the published config against your existing one. Major bumps that are "only dependency changes" still occasionally re-order or rename config keys as a side effect of refactoring.
4. First use case: run the package's own health path end-to-end — the artisan command, the facade call, or the HTTP route it registers — in a staging environment on the new PHP version before touching production. A dependency-only bump can still surface deprecation notices from your own code being exercised through a newly-upgraded Symfony component.

Implementation Patterns

Pin the major, float the minor. Use ^7.0 rather than 7.0.*. Since the breaking surface of this release is the platform requirement, you want patch releases (which typically fix compatibility with newly-released Symfony minors) to flow in without a manual bump.

Upgrade in the same PR as the PHP bump, not before. The most common workflow failure is bumping the package first and the PHP image second, which leaves the branch un-installable for the whole review cycle. Land them together:

"require": {
    "php": "^8.2",
    "<vendor>/<package>": "^7.0"
}

Refresh config cache as part of deploy. Because this release can change config shape, add php artisan config:clear (or config:cache) to the deploy script before the package's own commands run. Do not rely on a cached config from the previous major surviving the switch.

Use a compatibility shim if you cannot move the whole app at once. If the package is a leaf dependency (e.g. only used in one job or one controller), you can often run it in a separate service or a queued worker on the new PHP runtime while the monolith stays behind. Watch for shared config/cache keys in that split.

Test the Symfony surface you actually touch. If your code injects Symfony contracts (Command, Request, Response) alongside the package, the refreshed constraints are the real risk area. Add an integration test that boots the container and resolves the package's bindings — that catches container-definition drift far faster than unit tests.

Wire it into CI explicitly. Add a matrix entry for the minimum supported PHP so the next dependency bump does not silently raise the floor again without a failing build.

Gotchas and Tips

• composer why-not <vendor>/<package> 7.0 is your first debugging command. When the install fails, it names the exact package holding back the Symfony version. Do not guess at the conflict.
• --with-all-dependencies vs --with-dependencies: the former allows root requirements to move. Without it you will see a conflict reported against a package you never mentioned.
• Lockfile drift in transitive Symfony packages is expected and safe if your own direct symfony/* constraints are permissive. If you pin symfony/console to an exact version, the package's raised floor will hard-conflict — loosen to ^6.4 || ^7.0 style ranges rather than fighting the resolver.
• Deprecation noise is not a failure. Running on the new PHP version will surface E_DEPRECATED from your own code and from unrelated dependencies. Convert these to a non-blocking log channel rather than suppressing globally, so genuine package warnings stay visible.
• Clearing the wrong cache is a classic false negative. If behaviour looks unchanged after upgrade, confirm you are not running against an opcache/APCu-cached copy of the old package in a long-lived PHP-FPM worker — restart the pool.
• Extension points generally survive dependency-only majors, but verify by contract, not by memory. If you extend a package class or implement its interfaces, run a static analysis pass (phpstan/psalm at your baseline level) against the new version. Refactors driven by a Symfony upgrade are the usual source of signature changes in abstract classes.
• Check the package's own CI matrix in its repo before upgrading your production PHP. If the maintainers have not tested against the newest PHP minor you plan to deploy, treat that combination as unsupported and stage it carefully.
• Versioning signal: a 7.0.0 that only bumps platform requirements is a strong hint the maintainers are clearing the deck for feature work. Watch the 7.x patch line for follow-up releases and re-read the changelog then — this assessment will need revisiting once real API changes land.