Prompt Laravel Package

Getting Started

This release is a compatibility release: v1.2.0 adds support for Laravel 13 (and later). The package's day-to-day surface is unchanged, so the fastest path is to confirm you are on a version that will actually install, then exercise your existing integration once on the new framework.

1. Confirm the constraint actually widened. Before upgrading Laravel, check what the package now allows:

   composer show <vendor>/<package> --all | grep -A5 requires
   

   You are looking for illuminate/* / laravel/framework constraints that include ^13.0. If the constraint is still ^11.0|^12.0, the release note does not apply to your install and Composer will refuse the upgrade — that is the first thing to verify, not a bug in your app.
2. Install on the new major. Either bump Laravel first and let Composer resolve the package, or pin explicitly so the upgrade is reproducible:

   composer require <vendor>/<package>:"^1.2" laravel/framework:"^13.0" --with-all-dependencies
   

   --with-all-dependencies matters here: the package's own dependencies may have moved their Laravel constraints in lockstep, and a partial update will fail with a misleading conflict message.
3. Re-run discovery and clear caches. Laravel 13 projects should still auto-discover the service provider, but if you upgraded in place, stale manifests are the usual cause of "class not found" after a major bump:

   php artisan package:discover
   php artisan optimize:clear
   

4. First use case: a smoke test, not a feature. Take the single place in your app where you rely on the package most (a queued job, a middleware, a form request validation rule — whatever the package's core entry point is for you) and run that test file only. That answers "does this package still work on 13?" in seconds, before you run a full suite against a new framework version.

Where to look first if something breaks: the package's composer.json (what it claims to support), its src/ service provider (what it binds and when), and your own config/ published file (what you overrode long ago and forgot about).

Implementation Patterns

Treat the framework version as a matrix dimension, not a single value. The reason to upgrade to v1.2.0 is usually that you want to move to Laravel 13 while other parts of the codebase (or other packages) are still on 12. Add both to CI rather than doing a big-bang switch:

# .github/workflows/tests.yml
strategy:
  matrix:
    laravel: ['12.*', '13.*']
    include:
      - laravel: '12.*'
        testbench: '10.*'
      - laravel: '13.*'
        testbench: '11.*'

If you use orchestra/testbench for package-level tests, its major version is tied to the Laravel major — mismatched Testbench is the single most common reason a "supported" combination fails in CI while working locally.

Pin the package, float the framework — or the reverse, but not both. In composer.json, prefer a caret constraint on the package ("^1.2") and let the framework float within its major ("^13.0"). Avoid dev-main for the package during a framework migration: you lose the ability to bisect a regression between "framework changed" and "package changed."

Use the upgrade as an excuse to isolate your integration surface. If the package is called from more than a handful of files, wrap it. After a framework major, the wrapper is the only file that needs auditing:

final class ThingGateway
{
    public function __construct(private readonly PackageClient $client) {}

    public function send(Thing $thing): Result
    {
        return $this->client->dispatch($thing->toPackagePayload());
    }
}

This also makes the next compatibility bump (13 → 14) a one-file review instead of a codebase-wide grep.

Bind configuration per environment, not per version. Resist adding if (app()->version() >= 13) branches around package calls. Framework-conditional code inside application logic is a maintenance trap — it survives long after the old version is gone and silently stops being tested. If behaviour genuinely differs between 12 and 13, express it as a config value or a bound interface implementation chosen in a service provider.

Regression-test the queue and the HTTP layer specifically. Framework majors most often change behaviour in job serialization/retry semantics, middleware ordering, and validation rule internals. If the package touches any of those, a passing unit suite is not evidence; run one real queued job and one real request in a staging environment.

Gotchas and Tips

• "Laravel 13 and further" is not a contract. The phrase implies forward compatibility, but Composer constraints are what actually decide. If the published constraint is ^13.0 only, Laravel 14 will be blocked at install time regardless of the release note's wording — and that is fine, just don't plan around it.
• Transitive constraints bite last. A package supporting Laravel 13 says nothing about the packages it depends on. When composer update fails with a conflict, read the conflict tree bottom-up (composer why-not laravel/framework 13.*) rather than top-down; the blocking package is usually two levels deep and not the one named in the error headline.
• PHP version floor moves with the framework. Laravel 13 raises the minimum PHP version. If your CI or a deploy target is still on an older PHP, the install will fail on the platform requirement check — and --ignore-platform-reqs is not a fix, it just relocates the failure to runtime.
• Deprecations are silent until they aren't. Framework majors remove things that were deprecated in the prior major. Run with deprecation reporting on during the upgrade window:

  php -d error_reporting=E_ALL vendor/bin/phpunit
  

  Packages commonly still call a removed helper internally while their own tests pass, because their tests don't exercise the path your app does.
• Clear compiled config and cached providers after the bump. bootstrap/cache/*.php from the previous major can reference class names or signatures that changed. php artisan optimize:clear before you start debugging anything else — it resolves a surprising share of "works locally, breaks on deploy" reports.
• Check the changelog between your version and 1.2.0, not just the 1.2.0 note. The release note describes one change; intermediate patch releases may carry behaviour fixes you want (or need to account for). Compare tags directly if the changelog is thin.
• Extension points to verify rather than trust: published config merge behaviour, any facade alias, and any container binding the package registers. If you have overridden a binding in your own provider, confirm it still wins on 13 — provider registration order across package discovery is the kind of thing that shifts quietly between majors.
• If the package has no tests against 13, assume nothing. Run your own integration test against the new major before upgrading production. A version constraint is a claim, and for a single-line release note it is worth ten minutes to verify the claim against your actual usage.