Laravel Shopify Laravel Package

Getting Started

This is a patch release (v1.2.9) whose only stated change is "Prepare for Laravel 12". Treat it as a compatibility release, not a feature release. There is no prior assessment to diff against, so start by confirming what the bump actually changed rather than assuming.

Minimal steps:

1. Inspect the diff before upgrading. Run composer diff (or compare tags on the repo) and look specifically at composer.json. The meaningful question is whether the illuminate/* / laravel/framework constraint now permits ^12.0, and whether the minimum PHP constraint moved to >=8.2 (Laravel 12's floor).
2. Look first at the package's service provider and config file — that's where Laravel-version conditionals usually land in a "prepare for" release. If the provider branches on $this->app->version(), that's your signal the package had to paper over a framework API change.
3. First use case: drop it into a Laravel 11 app first (composer require with the new tag), run your test suite, and only then attempt a Laravel 12 skeleton. Shipping straight to 12 conflates two failure sources.

If the changelog is genuinely a one-liner, the fastest signal is the CI matrix in the repo — a row for Laravel 12 tells you the maintainer actually tests it; its absence tells you the constraint was merely widened.

Implementation Patterns

Pin the framework, not the package. The recurring risk with "prepare for Laravel N" patches is that the composer constraint is loosened before the test matrix catches up. In application code:

"require": {
    "php": "^8.2",
    "laravel/framework": "^12.0",
    "vendor/package": "^1.2.9"
}

Constrain the framework explicitly so a transitive upgrade can't silently drag you onto 12 mid-sprint.

Verify compatibility in a throwaway branch, not in main. Because this release may only touch metadata, the practical workflow is:

git checkout -b chore/laravel-12-dryrun
composer update vendor/package --with-all-dependencies
php artisan about          # confirms framework + package boot together
php artisan test

Watch the container bindings. Packages that "prepare for" a new major often shift from singleton to scoped bindings, or from register() to boot() wiring, to align with newer framework lifecycle expectations. If you resolve the package's services in a queued job or an Octane worker, a binding-scope change is the most likely thing to bite you — re-verify state isolation if you run under Octane.

Use the upgrade as a forcing function for your own test coverage. If your suite doesn't exercise the package's public surface, this is the moment to add a smoke test around its primary entry point. A compatibility release with no behaviour change should be provable as a no-op by your own tests, which gives you a clean baseline for the next major.

Check the deprecation channel. Laravel 12 preparation frequently means silencing deprecations in the package and surfacing new ones. Run with APP_DEBUG=true and a strict error handler in staging; PHP 8.4 deprecations (implicit nullable types are the usual offender) surface here and are cheap to fix now, expensive after 13.

Gotchas and Tips

• "Prepare for" is not "supports". A widened constraint and a green CI job are different claims. Confirm which one you're getting. If the repo's CI has no Laravel 12 job, treat it as untested and budget time for your own verification.
• Patch-version trap. Semver says v1.2.9 is non-breaking, and it almost certainly is for Laravel 10/11 users — but the PHP floor can still move in a patch. Check that your production PHP version satisfies the new constraint before deploying; a floor bump is the usual way a "harmless" patch breaks a deploy.
• Composer resolution weirdness. Widened constraints can let Composer satisfy the package with a framework version it never intended. After upgrading, run composer why laravel/framework and composer show vendor/package to confirm the actual resolved pair, not the declared one.
• Debugging a boot failure: if the app errors during provider registration after upgrade, the cause is almost always an ordering or method-signature difference. Bisect by temporarily registering the provider conditionally in bootstrap/providers.php and inspecting php artisan about or php artisan package:discover -v.
• Config quirks: if the release touched config/*.php, an already-published config file in your app will not be updated. Diff the package's shipped config against yours (php artisan vendor:publish --tag=<tag> --force into a scratch directory to compare) — removed keys silently fall back to defaults, added keys are silently absent.
• Extension points worth re-checking: published views, custom bindings overriding the package's contracts, and any Macroable registration. Compatibility releases often tighten visibility or add final/return types, which breaks subclasses in userland without any runtime error until the method is called.
• Don't batch this with a feature upgrade. Keep the compatibility bump in its own commit so a rollback is a single revert rather than an archaeology exercise.