Laravel Cancellation Laravel Package

Getting Started

• Confirm the runtime first. v1.5.0 adds PHP 8 support, so the very first step is php -v on every environment (local, CI, staging, prod). If any host is on 7.4, v1.5.0 is not a drop-in — either upgrade the host or hold the constraint at the last 7.x-compatible release.
• Bump the constraint explicitly: composer require vendor/package:^1.5 rather than a bare composer update, so the intent is recorded in composer.json and reviewable in the PR.
• Re-publish assets only if the changelog says to. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config (and --tag=migrations if applicable) and diff against your committed copies before accepting.
• Look first at the package's service provider. It tells you what is bound into the container, what is registered as a singleton, and which config keys are actually read — that is the real API surface, not the README.
• Clear the caches. php artisan config:clear && php artisan cache:clear && composer dump-autoload after the upgrade; config caching is the single most common cause of "the upgrade did nothing / everything broke."
• First use case: resolve the package's main entry point out of the container once, by hand, in php artisan tinker, and exercise a single read-only call against real config. If that works, the rest is wiring; if it fails, you've found the problem in 30 seconds instead of in a queued job at 2am.

Implementation Patterns

• Prefer constructor injection over facades in your own classes. Packages that support PHP 8 are usually modernised internally, and the container binding is the stable seam — facades are convenient but couple your tests to the package's static state.
• Wrap it in a thin adapter. One small class of your own that owns the package calls, with an interface bound in a service provider. This is what makes the next major version (or a swap-out) a one-file change instead of a grep across the codebase.
• Keep configuration in config/, not in code. Reference config keys through config('package.key') inside your adapter only; sprinkle them through controllers and you've made the package impossible to remove.
• Use it behind queues for anything slow. If the package does I/O (HTTP, storage, external APIs), call it from a job with sensible $tries/$backoff and make the call idempotent. Retries are where third-party packages hurt you.
• Test against a real instance where feasible. Use RefreshDatabase for anything touching storage; use fakes (Http::fake(), Queue::fake(), Storage::fake()) only for the boundaries the package actually crosses. Faking the package itself usually tests nothing.
• Take advantage of PHP 8 idioms in your wrappers now that the floor is 8.0: constructor property promotion, named arguments for readability at call sites, union types and match in your own translation layer between your domain and the package's API.
• CI matrix: run 8.0/8.1/8.2/8.3 against the Laravel versions you actually support. v1.5.0 claiming PHP 8 support doesn't mean every 8.x patch is tested upstream — your matrix is the proof.
• If you publish a shared internal package that depends on this one, widen rather than tighten: ^1.4 || ^1.5 avoids forcing every downstream app to upgrade in lockstep.

Gotchas and Tips

• "Supports PHP 8" is a floor, not a ceiling. PHP 8.0 is end-of-life. Treat v1.5.0 as a stepping stone to 8.1+ rather than a reason to standardise on 8.0 — you'll take a second migration later otherwise.
• Minor version, potential caller-side breakage. If the release added native parameter types or renamed parameters (common when a package formalises PHP 8 support), your calls can break even though ^1.5 is semver-compatible:
  • Named arguments (foo(thing: $x)) break silently-loudly on any parameter rename.
  • New union/native types reject null or loose scalars that docblocks previously allowed.
  • Tightened return types can break subclasses you wrote by extending the package.
• Run your full test suite before deploying, not after. Do it on the same PHP minor as production; a green run on 8.3 tells you very little about 8.0.
• Watch for PHP 8.2 dynamic-property deprecations surfacing from the package or from your own subclasses of it — noisy, but they are warnings of real breakage in 9.0.
• Framework alignment: Laravel 9+ requires PHP 8, Laravel 8 supports 7.3+. If you're pinning the package upgrade to a framework upgrade, do them as one change with one rollback plan, not two.
• Pin the PHP version in CI and in your Docker base image. The most common post-upgrade failure is a CI runner silently on a different PHP minor than production, so tests pass and deploys break.
• Extension points worth knowing before you need them: binding an interface to your own implementation in a service provider, overriding published config per environment, and (if offered) the events the package dispatches — listening to those is usually cleaner than wrapping every call.
• Read the actual diff, not just the headline. A one-line release note often hides several patch releases' worth of changes. composer update --dry-run -v plus the full changelog is five minutes well spent before this touches production.