Laravel Snapshot Laravel Package

Getting Started

v2.1.0 is a platform-floor release only — no API changes, no new features, no deprecations. The entire day-to-day workflow you already have keeps working; what changes is where it is allowed to run. Treat this as an infrastructure upgrade, not a feature upgrade.

Minimum steps to adopt:

1. Verify your runtime before touching Composer.

   php -v          # must report 8.4.x or 8.5.x
   composer check-platform-reqs
   

2. Bump the constraint in your root composer.json:

   "require": { "php": "^8.4" }
   

   (Or leave it and let the package's own ^8.4 requirement fail the resolver loudly — either is fine, but pinning yours explicitly gives a clearer error message.)
3. Update and run the suite.

   composer update --with-all-dependencies
   php artisan test
   

4. Rebuild any containerised runtime. Sail/Docker/Devcontainer base images, Forge/Render/Fly build images, and CI runner images all need an 8.4 tag. A stale php:8.3-fpm image is the single most common failure mode here.

Where to look first:

• The package's composer.json → require.php and require-dev — confirm the floor and whether laravel/framework constraints moved alongside it (they did not in the notes, so your Laravel version support is unchanged).
• Your own composer.lock → platform-overrides and the resolved PHP version.
• Your deployment pipeline's PHP version, before your local machine. Local-first upgrades that aren't mirrored in CI produce green-local / red-deploy surprises.

First use case: the upgrade itself. A typical Laravel app on 8.3 upgrading to this release is a three-commit change — (a) composer.json platform pin, (b) Dockerfile/CI image tag, (c) any config.platform.php in composer.json. Ship it as its own PR with no other dependency bumps so a failure is unambiguous.

Implementation Patterns

Pin the platform explicitly. Add to root composer.json so local, CI, and prod agree:

"config": {
    "platform": { "php": "8.4.0" }
}

This makes Composer resolve as if it were on 8.4 regardless of the actual CLI binary, which prevents a developer on 8.3 from generating a lock file that breaks everyone else. Pair it with composer check-platform-reqs in CI to catch the inverse case (lock resolved for 8.4, runtime is 8.3).

Stagger the CI matrix. The upstream now tests 8.4 and 8.5. Mirror that, but keep 8.5 non-blocking until it is a stable production target for you:

strategy:
  fail-fast: false
  matrix:
    php: ['8.4', '8.5']
    include:
      - php: '8.4'
        coverage: true

Mark 8.5 continue-on-error: true if you are not yet deploying on it — you want its deprecation warnings visible without blocking merges on an unstable runtime.

Sequence the rollout. Environment first, then code:

1. Local runtime → 8.4
2. CI image → 8.4 (this is the gate)
3. Staging deploy image → 8.4
4. Production

Do not bump composer.json before step 2; a lock file requiring 8.4 will fail to install on an 8.3 CI runner and you will spend time diagnosing the wrong layer.

Use PHP 8.4 language features deliberately, if at all. Property hooks and asymmetric visibility (private(set)) are the tempting ones. If you extend this package's classes and rely on inheritance, note that overriding a private(set) property or a hooked property has stricter rules than a plain one — check that your subclasses still typecheck before adopting them in code that touches package internals.

Guard against transitive drift. composer update --with-all-dependencies can pull unrelated minor bumps. If you want a surgical upgrade, use composer update vendor/package --with-dependencies so only this package and its direct dependency tree move.

Gotchas and Tips

Managed hosting lags. Shared hosts, some PaaS default runtimes, and control-panel PHP selectors routinely trail new PHP minors by months. Verify your actual target supports 8.4 before merging; a passing CI run on GitHub Actions says nothing about your production host.

Dependency caps block you, not the package. The usual failure is not this package requiring 8.4 — it is a transitive dependency capping at ~8.3.0. Diagnose with:

composer why-not php 8.4
composer prohibits php 8.4

prohibits gives you the full chain; why-not gives you the shortest answer. Then decide whether to wait, fork, or find an alternative.

Stale Composer cache and vendor dirs. After changing the platform pin, delete vendor/ and composer.lock if resolution looks impossible but the constraints seem fine. Composer caches platform metadata aggressively.

PHP 8.5 is a moving target. If the upstream matrix includes 8.5, that almost certainly means a dev/pre-release build. Expect deprecation notices and occasional false failures there; do not treat 8.5 red as a defect in your code without confirming against the 8.4 job first.

Deployment images and OPcache. Bumping the PHP tag means OPcache bytecode is invalidated and JIT settings may reset to defaults. If you had tuned opcache.jit or opcache.memory_consumption in an 8.3 image, re-apply those settings to the new image — they are not carried over by a tag change.

Extension points: unchanged. This release adds, removes, and renames nothing. Service providers, config publishing, facades, and any extension hooks behave identically to the previous version. If you have a pinned ~2.0 constraint and are not ready for 8.4, staying on 2.0.x is safe — there is nothing in 2.1.0 you are missing functionally.

Debugging checklist when things break post-upgrade: confirm php -v on the runner not just locally → composer check-platform-reqs → composer prohibits php 8.4 → inspect the container image tag in the failing job log → clear Composer cache → rebuild from a clean vendor/. In practice, steps 1 and 4 resolve the majority of reports.

Scope note: this assessment is derived solely from the v2.1.0 release notes, which describe a runtime floor change and nothing else. Confirm against the package README and changelog whether the platform bump shipped alongside any documentation-only clarifications relevant to your integration.