Deaths Tar Vulnerability Laravel Package

Getting Started

1. Install and pin the major. composer require vendor/package:^2.0 — the 2.0 bump means the constraint should be explicit in composer.json rather than a floating *, so a future minor can't silently change behaviour in CI.
2. Publish and diff the config. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config and commit the result. On a major release the published config is the most likely place for renamed or removed keys, and having it in version control makes the upgrade diff obvious.
3. Read the upgrade guide before the changelog. The three bullets in 2.0.0 ("a new feature", "a fix", "another fix") are not actionable on their own — treat the linked UPGRADE.md (or the compare view between v1.x and v2.0.0) as the real source of truth for removed methods, changed defaults, and bumped PHP/Laravel minimums.
4. Smoke-test the happy path first. Wire the package into a single existing feature — one controller or one queued job — and confirm the container resolves it, the facade alias is registered, and the config is read from config/package.php. Don't migrate every call site before you know the boot path works.
5. First real use case: find the one place in your app that hand-rolls the behaviour the package provides (custom validation, an HTTP client wrapper, a reporting query) and replace only that. It gives you a contained before/after to validate against and a rollback that is a single revert.

Implementation Patterns

• Resolve from the container, don't new it up. Inject the package's contracts into constructors and let the service provider bind them. This keeps your code testable with $this->mock() and survives the package swapping its concrete class in a minor release.
• Wrap third-party surface area in your own adapter. Create a thin App\Support\… class that delegates to the package and expose that through your own interface. When 3.0 arrives, or when you swap packages, only the adapter changes — not forty call sites.
• Prefer events and jobs over inline calls. If the package dispatches events, listen to them rather than polling its state in a controller. If it does slow work (HTTP, file IO), push it onto a queue and give it a retryUntil plus a unique job constraint.
• Two-tier config. Keep package defaults untouched in config/package.php; layer environment-specific overrides in config/services.php or a dedicated config/package_overrides.php read from env. Makes staging vs production drift visible in php artisan config:show.
• Register in the provider, not the bootstrap file. Service provider register() for bindings, boot() for publishes, commands, and migrations. Avoid touching AppServiceProvider::boot() for anything beyond a single configure call.
• Test against the package's fakes. Most Laravel packages ship a fake or an in-memory driver. Use it in feature tests and reserve integration tests (real HTTP, real DB) for a small number of cases — otherwise the suite becomes slow and flaky after a major bump.
• Gate the rollout with a feature flag. On a major version, ship behind Laravel Pennant or a config toggle so you can compare old and new behaviour in production for a week before deleting the old path.

Gotchas and Tips

• Vague changelogs hide silent default changes. "A fix" frequently means a default flipped from true to false or a signature gained a parameter. After upgrading, run php artisan config:show vendor-package and grep your app for every config key the package reads — an unset key now falling back differently is the classic post-major bug.
• Clear every cache layer. php artisan config:clear && php artisan cache:clear && composer dump-autoload — a stale cached config or an old classmap is the #1 cause of "it works locally but not in CI" after a version bump. In Octane, also php artisan octane:reload; long-lived workers hold the old container.
• Watch for static and singleton state. Packages that cache resolvers, connections, or config in static properties behave differently under Octane and in parallel test runs (--parallel). If tests pass serially and fail in parallel, this is almost always the cause.
• Check the facade alias. If 2.0 renamed the alias in extra.laravel.aliases, every Package:: call in your app breaks with a confusing "class not found". Either keep the old alias registered yourself in config/app.php or do a project-wide rename in one commit.
• Migrations and publish tags are versioned. Re-publishing with --force will overwrite your edited config or migration. Publish to a temp path, diff, then merge — especially on a major where the package's own migration may have changed.
• Debug with the package's own logging before yours. Set its log channel to daily at debug level in a local .env, reproduce, and read the raw payloads. Guessing at serialization or DTO shapes wastes far more time than a noisy log.
• Extension points beat forking. Before patching vendor code, check for a Macroable trait, a Factory, a resolvable contract, or an event you can hook. Container binding an interface to your own subclass is the sanctioned override — a composer patch will not survive the next composer update.
• Pin and automate. Commit composer.lock, and add Dependabot/Renovate with a separate PR group for majors so a 2.0 → 3.0 bump lands alone, with the full test suite as the gate, rather than buried in a routine dependency refresh.