Laravel Beekeeper Laravel Package

Getting Started

v13.0.0 is a platform-only major: it adds support for Laravel 13 and PHP 8.4/8.5, and drops Laravel 12 and PHP 8.2/8.3. There are no new end-user features to learn, so the first thing to do is confirm you can even install it:

composer require your-vendor/this-package:^13.0 --with-all-dependencies
php artisan --version   # must be 13.x
php -v                  # must be 8.4+

If Composer resolves to ^12.x instead, your app or a transitive dependency is still pinned to Laravel 12 / PHP 8.2–8.3 — that is the upgrade signal, not a package bug.

Where to look first:

1. composer.json of your app — bump php to ^8.4 and laravel/framework to ^13.0.
2. The package's CHANGELOG/UPGRADING file — confirm whether v13 ships config or migration changes alongside the platform bump.
3. config/ publish output — if the package publishes config, diff it against what you have committed.

First use case: run the package's own test suite path in your app before touching feature code.

php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --force
php artisan config:clear && php artisan cache:clear
php artisan test --filter=PackageIntegration

If you have an integration test that exercises the package (a job, a route, a model observer), that single test passing on Laravel 13 is your green light. If you don't have one, write one now — it is the cheapest insurance for the next major.

Implementation Patterns

Pin the constraint, not the lockfile. In composer.json, require "your-vendor/this-package": "^13.0" and let the platform constraints do the work. Avoid "*" — with a package that follows Laravel's major cadence, ^13.0 correctly excludes future 14.x breaking changes.

Keep the upgrade in its own PR. A platform-only major has zero intended behaviour change, so it should be a mechanically reviewable diff: composer.json, composer.lock, CI matrix, and nothing else. Any application code change in that PR is either a hidden breaking change or scope creep — split it out.

CI matrix as the source of truth. Encode the new floor explicitly so the constraint can't silently drift back:

strategy:
  matrix:
    php: ['8.4', '8.5']
    laravel: ['13.*']

Also add a composer why-not your-vendor/this-package 13.0.0 step — it prints the exact package blocking the resolution, which is far faster than reading solver output.

Service provider and config registration. If the package registers a provider, confirm it still auto-discovers after the bump (php artisan about lists discovered providers). If you register it manually in bootstrap/providers.php (Laravel 11+ style), verify the file still exists at the path you reference — provider class moves are a common companion to major releases.

Facade/entry-point wrapping. If you call the package from more than a handful of places, wrap it in your own thin service and bind it in a provider. That way the next platform major touches one class instead of fifty call sites:

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

    public function push(array $payload): void
    {
        $this->client->send($payload);
    }
}

Queue and container integration. If the package dispatches jobs or resolves services from the container, run a real worker against Laravel 13 rather than only hitting it synchronously in tests — serialization of package value objects across the queue boundary is exactly the class of thing a framework major can shift.

Local dev alignment. Update docker-compose/Dockerfile/Herd/Valet PHP version in the same PR. A passing CI on 8.4 and a local box on 8.3 produces confusing, non-reproducible failures.

Gotchas and Tips

• --with-all-dependencies is not optional. Without -W, Composer will happily keep Laravel 12 installed and report a version conflict that looks like a package bug. It is a solver problem.
• Read the error, then run composer why-not. Every failed upgrade of this kind is one of: app pins old Laravel, a third-party package pins old Laravel/PHP, or CI uses an old PHP image. composer why-not laravel/framework 13.0 names it directly.
• CI images lag. shivammathur/setup-php and most base Docker images need php-version: '8.5' set explicitly; latest frequently resolves to 8.3 or 8.4. Pin it.
• Laravel 12-only APIs. Dropping Laravel 12 means anything the package used that was removed in 13 is gone. If you extended package internals (subclassed a class, decorated a binding, overrode a protected method), re-read the source — extending internals is the number one source of surprise breakage on a platform major.
• Deprecation noise before the bump. Get to a clean php -d error_reporting=E_ALL artisan test on 8.4 while still on v12 — that surfaces the deprecations v13 turns into errors, and separates "package broke" from "we were already on borrowed time."
• Config cache is a liar. After upgrading, always php artisan config:clear (and optimize:clear) before debugging. Stale cached config from the previous major produces failures that don't reproduce in a fresh checkout.
• Published assets drift. If the package publishes migrations or config, v13 may have changed the canonical version. Diff rather than --force overwrite in production databases; a --force republish on a live schema is how you lose an afternoon.
• Check the package's own support policy. A package that tracks Laravel majors this tightly will ship v14 shortly after Laravel 14. Budget for this being a recurring, low-effort per-year upgrade rather than a one-off — that framing is what makes ^13.0 obviously correct over a looser constraint.
• No feature work in this release means no release-notes reading payoff. Don't hunt for new capabilities; spend the time on the integration test and CI matrix instead.

Bottom line: v13.0.0 is a breaking-change major in the platform sense only. Upgrade if you are on or moving to Laravel 13 / PHP 8.4+; if you are stuck on Laravel 12 or PHP 8.2/8.3, stay on v12.x — and note that v12.x will stop receiving fixes, so treat the platform upgrade as scheduled work rather than optional.