Laravel Recombee Laravel Package

Getting Started

This package is still pre-1.0 (0.2.2), so treat the API as stabilising rather than stable. The most important thing to know about this release is that it is a compatibility release, not a feature release: Laravel 13 support has been added, and nothing else in the notes suggests behaviour changes.

Start here:

1. Check the constraint before you install. Run composer show <vendor>/<package> --all and confirm the laravel/framework / illuminate/* constraint in composer.json actually includes ^13.0. A release note saying "added support" is not the same as a constraint that resolves cleanly in your project — verify with composer why-not laravel/framework 13.* if the resolver fights you.
2. Confirm the PHP floor. Laravel 13 raises the minimum PHP version; if 0.2.2 follows the framework, your CI matrix and any deployed runtime need to match before you bump. Run composer update <vendor>/<package> --with-dependencies --dry-run first.
3. Read the service provider. Most Laravel packages auto-register via extra.laravel.providers. Check whether config, migrations, or views need publishing (php artisan vendor:publish --provider="..."), and whether the package ships an install command.
4. Run the package's own test suite or a smoke test in a throwaway Laravel 13 app before touching production constraints.

First use case: upgrade an existing Laravel 12 application on 0.2.1 to 0.2.2 + Laravel 13 in a branch, run your existing test suite, and only then start using the package's primary feature. The bump is the thing being validated here; new functionality is not on offer.

Implementation Patterns

Pin the pair, not just the package. Because 0.2.2 exists specifically to unlock Laravel 13, your composer.json should express the relationship explicitly in a comment or in CI docs. A constraint like "<vendor>/<package>": "^0.2.2" combined with "laravel/framework": "^13.0" documents intent, and lets you drop the ^0.2.2 floor the moment you no longer need Laravel 12 support.

Resolve dependencies in the package, not the app. If you maintain downstream packages that depend on this one, bump their constraints too and test the combination. The failure mode here is a diamond dependency: the app upgrades to Laravel 13, but a third-party package still pins illuminate/support ^12.0 and blocks the resolution.

Keep framework-version differences out of your application code. Laravel 13 support added in a patch/minor release usually means internal adjustments to the package (service provider signatures, removed/renamed framework internals, typed config, possibly Illuminate\Contracts changes). Your integration code should not need to branch on app()->version(). If you find yourself writing version_compare(...) in a service class, that's a signal to file an issue rather than paper over it.

Test against both majors while you still can. Until you fully drop Laravel 12, run a CI matrix of {Laravel 12, Laravel 13} × {lowest, latest} dependency versions (composer update --prefer-lowest). This is the single highest-value pattern for a package whose value proposition is framework compatibility.

Use the container, not static calls, in your own code. Bind the package's client/manager in a service provider and inject it. If the package ships a facade, prefer constructor injection of the underlying class so tests can swap it without Facade::clearResolvedInstances() gymnastics.

Testing in Laravel 13 apps. Use RefreshDatabase for anything touching package migrations, and prefer fakes over HTTP mocks where the package provides them. If it doesn't provide fakes, wrap it in a thin adapter of your own — that adapter is also your insurance policy against 0.x breaking changes.

Gotchas and Tips

• Pre-1.0 semver is not your friend. In 0.x, a minor bump (0.2 → 0.3) is allowed to contain breaking changes. Pin to ~0.2.2 rather than ^0.2 if you want predictability, and read every changelog between patch releases.
• "Added support for Laravel 13" often means "dropped support for something." Release notes rarely mention the constraint that was removed. Inspect the diff of composer.json in the tagged release (composer show <vendor>/<package> 0.2.2 or the GitHub compare view) to see whether Laravel 10/11 or an older PHP version fell out of the matrix.
• Stale caches after upgrading. After any version bump: php artisan config:clear, php artisan cache:clear, composer dump-autoload. Package discovery is cached in bootstrap/cache/packages.php, and a stale manifest is the most common cause of "class not found" immediately after an upgrade.
• Config drift. If you published the package config in the past, new keys added by the package won't appear. Re-publish to a temp directory and diff against your published copy rather than blindly overwriting.
• Extension points. Before patching vendor code (never do this), look for: a bound interface you can rebind in your own provider, a config-driven driver/strategy, or published views/components you can override. Most Laravel packages leave at least one of these open — that is the intended customisation surface.
• Debugging resolution failures. composer why-not laravel/framework ^13.0 is the fastest way to find what is blocking the upgrade; composer prohibits gives the same information in a more verbose form.
• Upgrade order matters. Framework first (12 → 13), then packages, then application code. Doing it in the reverse order creates confusing failures that look like package bugs but are really framework API changes.
• Watch for a 1.0.0. A package that has just widened its framework support is often close to a stable release. If you're adopting this for long-lived production code, ask whether waiting for 1.0 is cheaper than absorbing a breaking change later.