Laravel Searchable Laravel Package

Getting Started

The 3.5.0 release is a compatibility release: the only documented change is support for Laravel 13. There are no new features, deprecations, or breaking changes in the notes, so an existing install on Laravel 10–12 should keep working after a routine composer update, and a Laravel 13 upgrade now becomes possible without swapping the package out.

Minimal steps:

1. composer require <vendor>/<package>:^3.5 — the constraint must resolve to 3.5.0 or later, since earlier 3.x tags will not declare Laravel 13 compatibility and Composer will refuse to install them alongside laravel/framework:^13.0.
2. Check the package's composer.json for the PHP floor and the illuminate/* constraints before upgrading the framework. Laravel 13 raises the platform requirements, so a package that "supports Laravel 13" implicitly requires a newer PHP than your Laravel 11 install may be pinned to.
3. Look first at the package's service provider and its config/ file — that is where every knob lives, and it is the fastest way to understand what the package actually registers (bindings, facades, migrations, routes, commands).
4. First use case: publish the config (php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"), set the credentials/options it needs in .env, and exercise one read-path call in php artisan tinker before wiring it into application code. That isolates "package is installed correctly" from "my integration is correct".

If you are adopting this package fresh rather than upgrading, pin ^3.5 from the start — there is no reason to sit on a 3.4 install that will block a future framework bump.

Implementation Patterns

Resolve from the container, don't instantiate. Laravel packages almost always register their client/manager as a singleton in the service provider. Constructor-inject the contract or the concrete class; it keeps the singleton, makes the dependency swappable in tests, and means config changes take effect without touching call sites.

Keep configuration in config/ + .env, never inline. Publish the config file, commit it, and read values via config('package.key') only. Because config is cached in production, this also gives you a clean config:cache workflow — the alternative (reading env() directly in application code) silently breaks the moment config caching is enabled.

Treat the package as an adapter boundary. Wrap calls to it in your own small service or repository class rather than sprinkling the package's API across controllers, jobs, and listeners. A single-file boundary is what makes the next major version (or a framework bump like this one) a one-file change instead of a grep-and-replace exercise.

Test with the framework's fakes, or with a thin fake of your wrapper. If the package ships a ::fake() or a testing trait, use it — it is usually cheaper and more faithful than mocking the underlying HTTP client. If it doesn't, mock your wrapper, not the package: mocking third-party internals couples your test suite to their implementation details and turns every minor release into a test-suite repair job.

Upgrade flow for framework bumps. Use a version matrix rather than a big-bang upgrade: bump the package to ^3.5 on your current Laravel version first, deploy, confirm nothing regressed, then move the framework constraint. Two small, independently revertable PRs beat one that mixes a package upgrade with a framework upgrade — if something breaks, you'll know which one caused it.

Queue and long-running processes. If the package does I/O, prefer dispatching it from a job over doing it in the request cycle. Register the package's listener/command hooks in the service provider rather than at arbitrary points in the app so the behaviour is discoverable.

Gotchas and Tips

• "Support for Laravel 13" is a dependency claim, not a code guarantee. It tells you the maintainer tested against L13 and widened the constraint; it does not tell you the package's own transitive dependencies are ready. Run composer why-not laravel/framework 13.* and composer outdated --direct before the framework bump — the blocker is usually a sibling package, not this one.
• Transitive constraint collisions are the most common failure. If another dependency still caps at illuminate/support:^12.0, Composer will fail to resolve and the error will point at the wrong package. Use composer why-not <package> 3.5.0 to find the actual conflict rather than downgrading blindly.
• PHP version drift. Laravel 13's minimum PHP is higher than Laravel 11's. Check CI images, Dockerfiles, and any platform config in composer.json — a stale config.platform.php entry will happily resolve to versions your runtime cannot execute.
• Clear caches after upgrading. php artisan config:clear && php artisan cache:clear && composer dump-autoload should be reflexive. A stale cached config referencing a renamed key produces confusing "works locally, fails in staging" behaviour.
• Watch the minor-version boundary. This is 3.5.0, a minor bump — semver says no breaking changes within 3.x. If you are coming from 2.x, read the 3.0 upgrade notes instead; the Laravel 13 note tells you nothing about that migration.
• Debugging: enable the package's own log channel or verbose flag before reaching for dd(). For registration problems, php artisan about and php artisan package:discover will confirm the provider was found; for resolution problems, bind a spy in a service provider and dump what the container actually hands you.
• Extension points, in order of preference: published config → container rebinding ($this->app->bind(...) in a later-registered provider) → the package's documented events/listeners → macros, if the package registers them. Subclassing the package's classes is the last resort; it is the thing most likely to break on the next minor release.
• Pin to ^3.5 and keep the lockfile committed. Since the package's headline value here is compatibility, you want deterministic resolution across your team and CI — and a fast, obvious diff the next time a framework-support release lands.