Laravel Service Laravel Package

Getting Started

3.1.0 is a compatibility release: it adds Laravel 10 and 11 support and does not advertise new APIs. That shapes how you should approach it — the work is mostly installation and verification, not learning a feature set.

• Read first: the README install section, any UPGRADE.md / CHANGELOG.md entry for 3.x, and the package's composer.json. The illuminate/* / laravel/framework constraints plus the php constraint are the only things 3.1.0 definitively changes, so check them before anything else.
• Version choice: if you are already on a 3.x release, 3.1.0 is a minor bump and should be a like-for-like swap. If you are on 2.x, treat it as a major upgrade and read the 3.0 notes, not the 3.1 notes.
• Install: composer require <vendor>/<package>:^3.1. If resolution fails, run composer why-not laravel/framework 11.* to identify which package is pinning you back — very often it is not this package but a sibling dependency.
• Verify auto-discovery: most Laravel packages register via extra.laravel.providers. If the README asks you to add a provider or alias to config/app.php, remember Laravel 11 removed that file — the correct location is bootstrap/providers.php.
• Publish config: php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" (or --tag=...), then diff the published config against the package's source default so you can see what you are overriding.
• First use case: install into a throwaway Laravel 11 app, publish config, run the single example from the README (a route, an artisan command, or a facade call), and confirm it works before touching your production app. That gives you a known-good reference to diff against when the real app misbehaves.

Implementation Patterns

• Bind behind an interface. Resolve the package through the container rather than calling a facade statically throughout your app. A one-line $this->app->bind(YourContract::class, fn ($app) => /* package-backed adapter */) in a service provider keeps the package swappable and gives you a seam to fake in tests.
• Adapter/wrapper class. Put the package's calls in a single App\Support\... class. When 3.2 or 4.0 lands, you change one file instead of grepping the codebase.
• Config over code. Publish the config file, keep the environment-specific values in .env, and make sure your deploy script runs php artisan config:cache — a package reading config() at boot time behaves differently once config is cached, so test that path explicitly.
• CI matrix for the migration. Run your test suite against both Laravel 10 and 11 for one release cycle. If the package ships its own suite, run vendor/bin/phpunit (or Pest) inside the package after install to confirm the environment is genuinely supported, not just resolvable.
• Behavioural tests, not internal tests. Assert on what the package returns or dispatches, not on concrete class names or protected methods. Minor releases like this one rarely break behaviour but frequently touch internals.
• Commit the lock file and pin ^3.1. Avoid dev-main on a package whose only release signal is framework support; you want reproducibility, not the newest commit.
• Wrap expensive work in a job. If the package touches storage, HTTP, or a queue, invoke it from a queued job rather than mid-request — that also makes it trivially retryable and observable.
• Feature-flag the cutover. On the Laravel 11 upgrade, put the package behind a config flag so you can disable it without a redeploy if the integration misbehaves.

Gotchas and Tips

• A minor bump is not a guarantee. 3.1.0 signals no intentional breaking change, but the release note is one line long. Read the actual diff of composer.json and any provider/config changes before deploying to production.
• Laravel 11 removed a lot of default config files (config/app.php, config/broadcasting.php, config/sanctum.php, and others) and moved middleware and exception handling into bootstrap/app.php. A package that reads config keys without defaults, or registers middleware in an old-style HTTP kernel, can behave differently on 11 even though it "supports" it. Grep the package for config('...') calls without a second default argument.
• PHP 8.2 is required by Laravel 11. If your app is on 8.1 you cannot take the upgrade at all; check composer show php and your Docker base image before debugging package behaviour that was never going to work.
• PHPUnit scaffolding differs between Laravel 10 (PHPUnit 9/10) and 11 (PHPUnit 10/11). Test failures immediately after the upgrade are often the harness, not the package — run a trivial assertion test first.
• Debug order of operations: php artisan about (confirm framework/PHP/cache driver) → composer show <vendor>/<package> (confirm 3.1.0 actually installed) → php artisan config:clear → php artisan package:discover if the provider is missing. Nine times out of ten it is a stale config or bootstrap cache, not the package.
• Provider boot order matters. If the package depends on another service being registered first, its auto-discovered provider may boot too early. Move it explicitly into bootstrap/providers.php to control ordering.
• Cache the negative result. If you hit a "class not found" after install, check bootstrap/cache/packages.php and services.php — Laravel caches discovery results and a half-finished composer require leaves them stale.
• Extension points to look for: published config, container bindings the provider exposes, events it dispatches, and any Macroable trait or driver/manager pattern. Prefer extending via those over subclassing concrete classes. If none are documented, treat the package as a black box and put the adapter wrapper in front of it.
• Watch for 3.2. This release is purely a support-widening change; the next minor is where feature work will land. Subscribing to the repo's releases is cheaper than re-auditing the package at the next Laravel bump.