Laravel Api Versioning Laravel Package

Getting Started

This package now targets Laravel 12 / PHP 8.4 only (v2.0.0). Before anything else, verify you actually satisfy that floor — it is stricter than Laravel 12's own minimum (Laravel 12 runs happily on PHP 8.2), so a working Laravel 12 app does not guarantee this package installs.

Minimal steps:

1. Confirm the runtime, not just the framework:

   php -v                 # must be >= 8.4.0
   php artisan --version  # must be 12.x
   composer show laravel/framework
   

2. Check what Composer thinks is possible before touching the lockfile:

   composer why-not vendor/package 2.0.0
   

   This is the fastest way to see whether the blocker is PHP, the framework constraint, or a transitive illuminate/* pin from another package.
3. Install and smoke-test in a throwaway Laravel 12 skeleton app first, not in your main codebase, so you learn the new surface area without a half-broken branch.
4. Where to look first: the package's CHANGELOG/UPGRADING file and the composer.json require block. The release notes here only mention the platform bump, so confirm whether v2.0.0 also republished config, migrations, or service-provider bindings.

First real use case: get one end-to-end path working in the skeleton app (config publish → provider boot → primary feature call) so you have a known-good reference before migrating.

Implementation Patterns

Treat the framework bump and the package bump as one change. v2.0.0 is a breaking release by definition — it cannot coexist with Laravel 11 or PHP 8.3. Don't try to stage them separately; the dependency graph will fight you.

CI matrix first, code second. Add a job pinned to PHP 8.4 + Laravel 12 and let it go green before merging anything:

- php: '8.4'
  laravel: '^12.0'
  composer: 'update --prefer-lowest --prefer-stable'

The --prefer-lowest run is what catches an over-permissive dependency that resolves to something incompatible at the bottom of the range.

Pin the platform in composer.json so developer machines and CI agree regardless of the host PHP:

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

This makes composer install fail loudly on a stale local runtime instead of silently resolving a v1.x install.

Upgrade ordering for multi-package apps: upgrade the framework to 12 first on a branch, run the suite, then add this package's ^2.0 constraint. Doing it in the reverse order means every other package's constraint error is conflated with this one's.

Dependency automation: group the framework + this package in a single Renovate/Dependabot PR rule. Split PRs will produce a permanently red CI until both land, which trains people to ignore the bot.

Rollout: ship behind your normal canary/staged path. A major that changes the supported platform is a good moment to confirm error rates on the first deploy rather than assuming test coverage caught everything.

Gotchas and Tips

• Laravel 12 ≠ PHP 8.4. This is the single most likely source of confusion. Your app can be fully Laravel 12 compliant and still be unable to install v2.0.0 because it's on PHP 8.2 or 8.3. The composer why-not output will say php — read it carefully before assuming it's a framework conflict.
• Docker/CI images lag. php:8.4-cli, shivammathur/setup-php@v2, Laravel Herd, Sail, and most base images need explicit version bumps. Stale images are the most common reason a "we already upgraded" branch fails in CI but works locally.
• --ignore-platform-reqs is a trap here. It will let v2.0.0 install on PHP 8.3 and then fail at runtime or, worse, on the first use of a PHP 8.4 language feature. Fix the image instead.
• PHP 8.4 deprecations. If you're newly arriving on 8.4, expect notices around implicit nullable parameter types (Type $x = null) in your own code and in older dev dependencies. These are warnings today but will bite on 8.5.
• Transitive pins. A third-party package that requires illuminate/support ^10|^11 will block the whole resolution even though this package is fine. composer why-not laravel/framework 12.* names the culprit faster than reading the full solver output.
• --with-all-dependencies. If you're upgrading in place rather than from a clean install, use composer update vendor/package --with-all-dependencies so Composer is allowed to move the shared illuminate/* constraints alongside it.
• Config and migration republishing. Majors frequently ship changed published assets. Check php artisan vendor:publish --provider="..." --tag=config output against your committed config before assuming your overrides still apply — a renamed key silently falls back to the package default.
• Extension points. There is nothing in these release notes about new hooks, drivers, or contracts; treat v2.0.0 as a platform-compatibility release until the changelog says otherwise. Diff the source if you rely on extending an internal class.
• Lockfile hygiene. Commit the lockfile with the upgrade, and have at least one reviewer confirm php and laravel/framework are the only major movements — a platform bump is a good moment for unrelated transitive churn to sneak in.