Navigator Laravel Package

Getting Started

Version 3.0.0 is a platform-only release: the only documented change is the framework floor moving to Laravel 13, with PHP 8.2 and Laravel 12 support removed. There are no new features, no new API surface, and no deprecations called out — so "getting started" in practice means verifying you can install it before you start using it.

1. Confirm your runtime gates, because they are now hard requirements:
   • PHP 8.3+ (php -v)
   • laravel/framework 13.x (php artisan about, or check composer.json)
2. Check whether your app can move at all:

   composer why-not vendor/package 3.0
   composer outdated --direct
   

   If the output points at php or laravel/framework, you are not blocked by this package — you are blocked by the framework upgrade itself.
3. Install/upgrade on a branch:

   composer require "vendor/package:^3.0" --with-all-dependencies
   

4. Look first at the package's README, its service provider, and (if it publishes one) its config file — the day-to-day entry point and config are unchanged by this release, so 2.x documentation still describes the behaviour you'll be using.
5. First use case: pick one existing integration in your app that uses the package, run it under the new versions in a feature test, and use that as the canary before touching anything else. Because the release is framework-support-only, a single passing path is strong evidence the rest will behave identically.

Implementation Patterns

Upgrade-then-adopt, not adopt-then-upgrade. Treat the framework bump and the package bump as one atomic change. In composer.json, bump the package constraint and the framework constraint in the same commit so you never produce a lockfile that mixes a Laravel 12 app with a package major that cannot install on it.

Pin by major, install by patch. Use "^3.0" rather than a fixed version. Since 3.0.0 is a compatibility release, any 3.x patch should be a safe drop-in — let Composer take them, and let your test suite be the gate.

Keep a dual-major window if you maintain more than one app. If some applications are still on Laravel 12, keep the 2.x line installable for them (e.g. a long-lived branch with "vendor/package": "^2.0 || ^3.0" in shared internal packages) and only tighten to ^3.0 once every consumer is on Laravel 13. Shared first-party packages are the usual place this bites: a loose || constraint there lets both app generations resolve cleanly.

CI matrix. Update the matrix to PHP 8.3 / 8.4 × Laravel 13 as the supported combination, and drop the PHP 8.2 leg entirely. If you still ship a 2.x-compatible branch, keep a separate Laravel 12 job pinned to that branch rather than trying to make one matrix cover both — the constraints are mutually exclusive now.

Package authors consuming this library. If you build on top of it, raise your own composer.json floor (php: ^8.3, illuminate/*: ^13.0) in the same release, and validate with Orchestra Testbench against the new major:

composer require --dev "orchestra/testbench:^11.0" -W

Staged rollout. Deploy to a canary or staging environment first and watch error rates for one full traffic cycle. The risk here is not behavioural drift in the package, it's the framework migration underneath it — a canary is how you separate the two when something breaks.

Gotchas and Tips

Composer will "succeed" without upgrading. The most common failure mode: you run composer require vendor/package:^3.0, and Composer resolves you back onto 2.x because your lockfile's platform or framework constraint can't satisfy the new major. Never assume the bump landed — verify:

composer show vendor/package | grep versions
composer why-not vendor/package 3.0

why-not is the single most useful diagnostic during this upgrade; it names the exact package and constraint blocking you.

A platform check on the wrong PHP is easy to miss. Local CLI, CI image, and production runtime often disagree. If CI runs 8.3 but the deploy image is 8.2, you'll get a green build and a failed install at release time. Pin the PHP version everywhere the app is built or installed.

Dropped Laravel 12 support is transitive, not local. Even if your own app is on Laravel 13, any third-party dependency whose composer.json still requires the package at ^2.0 will block the whole resolution. Because this was a framework-support-only release, expect a tail of packages that have not yet widened their constraints — check for those before you start the framework upgrade so you can schedule around them.

PHP 8.2 removal means the deprecations are now real. Anything that only emitted E_DEPRECATED under 8.2 — implicitly nullable parameters (string $x = null), dynamic properties, ${var} string interpolation — should already be fixed if you've been reading logs. Treat the upgrade as the deadline: run your suite with deprecations escalated to errors at least once.

Clear cached artifacts after upgrading. Package discovery and config caches survive a Composer update and will keep loading the old provider/config:

composer dump-autoload
php artisan optimize:clear

Diff any published assets. If the package publishes a config file or migrations, compare them against the vendor copies after upgrading — a config file published under 2.x won't pick up defaults added later, and this class of drift is silent. Re-publish to a temp path and diff rather than overwriting.

Extension points are unchanged. Since this release adds no features, the config keys, published migrations, and container bindings you rely on are the same ones you already use. That means customisations survive untouched — but it also means there is nothing new to learn; don't go looking for a migration guide beyond Laravel's own.

Version-pinning for risk-averse apps. If you can't take the framework bump yet, staying on 2.x is a legitimate choice as long as that line still receives security fixes. Track the package's release notes for the point where 2.x stops being patched, and set a calendar reminder rather than relying on memory.