Laravel Passport Memoized Laravel Package

Getting Started

This release (v1.0.6) is a compatibility patch: it widens the framework constraint to allow Laravel 12. It carries no new features, no deprecations, and no breaking changes — but it is the release that makes the package installable on a Laravel 12 application, so it is the minimum version to require if you are upgrading.

First steps:

1. Confirm the constraint actually moved. Before trusting the release note, check what Composer resolved:

   composer show <vendor>/<package>
   

   Verify the installed version is 1.0.6 or later and that illuminate/support (or laravel/framework) in its require block admits ^12.0. If your app is still pinned to an older tag, composer why-not <vendor>/<package> 1.0.6 tells you which constraint is blocking.

2. Read the service provider before anything else. For a 1.x package this is the fastest map of the public surface: what it binds into the container, which contracts it aliases, whether it registers a facade, and whether it publishes config, migrations, or views. That single file tells you more than the README about extension points.

3. Publish the config and diff it.

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Published config is your day-to-day control panel; keep it in version control so behaviour changes are reviewable.

4. First real use case: wire the package into one narrow path in your app — a single controller, job, or console command — and get it working end-to-end on Laravel 12 before touching anything else. A green path proves the framework bump is genuinely compatible in your application, not just in the package's CI.

If the package is already installed on Laravel 11, upgrading is a two-step: bump the package constraint first, run your test suite unchanged, then upgrade Laravel. Doing both at once makes it impossible to attribute a failure.

Implementation Patterns

Constrain, don't float. Pin the package with a caret constraint ("^1.0.6") and commit the composer.lock. Because this patch exists specifically to widen the Laravel constraint, a loose * constraint can silently pull a version whose framework support you haven't validated.

Resolve through the container, not new. Bind the package's classes via constructor injection in your own services and jobs. This is what makes the package swappable in tests and what keeps you honest about its public API — if you can't inject it, it probably isn't meant to be depended on directly.

final class SyncOrders
{
    public function __construct(private OrderSyncClient $client) {}

    public function __invoke(): void
    {
        $this->client->push(Order::pending()->get());
    }
}

Wrap it once. Put a thin application-owned adapter around the package's entry points. When a 1.x package changes a method signature in a minor release, you edit one file instead of grepping fifty call sites. It also gives you a natural place to mock in tests.

Layer config, don't edit vendor defaults. Override only the keys you care about in config/<package>.php and rely on env() in your .env for environment-specific values. If the package ships an env()-backed config, note that config:cache freezes it — see Gotchas.

Run it in a queued job for anything slow. If the package makes network calls, dispatches external work, or does heavy I/O, wrap the call in a job with $tries, $backoff, and failed() handling. Packages that are convenient in a controller are frequently a liability in a request cycle.

Test with the container, not the world. Use $this->mock() / $this->instance() to bind a fake implementation of the package's contract in feature tests, and keep a small number of integration tests that hit the real thing. For Laravel 12, confirm phpunit.xml still sets APP_KEY and your test DB — fresh 12.x skeletons occasionally need a nudge here.

Validate the upgrade with a matrix, not a single run. Run the suite on PHP 8.2 and your highest supported PHP version. Laravel 12 requires a modern PHP floor, so the framework bump is really a joint PHP-plus-framework bump; catching a PHP-version-only failure is much cheaper in CI than in production.

Gotchas and Tips

• "Allow Laravel 12" is a claim, not a guarantee. The patch widens a constraint; it does not prove every code path was exercised against 12.x. Check CHANGELOG and the CI matrix if the repo is public — if there's no Laravel 12 job in CI, your own test suite is the compatibility evidence.

• Stale Composer metadata is the usual culprit. If composer update won't move you to 1.0.6, clear the cache and retry:

  composer clear-cache
  composer update <vendor>/<package> --with-dependencies
  

  Also confirm you aren't resolving against a private mirror or a path/VCS repository pinned to an old commit.

• Config caching bites during deploys. If the package reads env() at runtime rather than only inside config/, php artisan config:cache will silently freeze values. The fix in your app is to keep env() calls in config/ only, and to run config:clear before config:cache in your deploy script.

• Auto-discovery can be disabled. If the package's provider isn't in bootstrap/providers.php (Laravel 11+ style) or config/app.php, check composer.json for dont-discover. If you've aliased or replaced the provider, document why — it's a common source of "works locally, not in prod" reports.

• Publishing is a one-way copy. vendor:publish will not overwrite existing files without --force, which is the right default but means config changes in newer package versions won't reach you automatically. Diff the package's config/ directory against yours after every minor bump.

• Semantic versioning is only a promise. At 1.0.6 the project is young and its patch cadence is fast. Read the diff between tags rather than assuming a patch is cosmetic — this release is, but the next one may not be.

• Watch the deprecation surface of the framework, not just the package. Laravel 12 removes several earlier deprecations. If a failure appears right after the upgrade, check whether it originates in the package or in framework APIs the package consumes — the stack trace usually tells you, but it's easy to blame the dependency.

• Extension points to look for (in the provider and config): container bindings you can override, contracts you can implement, driver- or manager-style resolution you can extend with a custom driver, and events you can listen for instead of subclassing internals. Prefer events and bindings to extending concrete classes — those are the seams that tend to survive minor releases.

• Pin and upgrade deliberately. Set the constraint to ^1.0.6 today, then let Renovate or Dependabot open PRs for subsequent patches. For a package whose recent releases are framework-compatibility bumps, automated PRs with a green test suite are exactly the right cadence.