Laravel Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^0.4.1. The 0.4.x line is the first to declare Laravel 9 support, so treat 0.4.1 as your minimum if the app is on Laravel 9. On Laravel 10/11, verify the constraint before assuming compatibility; a package that added Laravel 9 support in a patch release may not yet allow newer framework majors.
• Check composer.json in the package for its illuminate/* and PHP constraints. Laravel 9 requires PHP 8.0+, so if the package previously supported PHP 7.x, confirm your runtime and CI images match.
• Laravel auto-discovery should register the service provider. Run php artisan package:discover if you use a cached manifest, then inspect php artisan about to confirm the provider loaded.
• Look first at the package README's configuration and migration sections, then config/<package>.php after publishing. Publish only what you need: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config (and --tag=migrations separately if applicable).
• First use case: wire the package into a single, low-risk flow — one controller or one queued job — with default config. Confirm it resolves from the container (app(SomeContract::class)) before spreading it across the codebase.

Implementation Patterns

• Resolve through the container, not static calls. Prefer constructor injection of the package's contract/class over facades. This keeps your code testable and makes it trivial to swap in a fake or a decorator later.
• Wrap it in a thin application service. Put the package behind your own class (App\Services\...) that exposes only the operations your domain needs. When the package's API shifts between 0.x minors, you change one adapter instead of dozens of call sites.
• Drive behavior from config, not code. Keep credentials, endpoints, timeouts, and feature flags in config/<package>.php and reference them via config(). Override per-environment with env vars rather than editing published files in place.
• Use it inside jobs for anything slow. If the package makes HTTP calls, writes files, or hits a third-party API, call it from a queued job with retries and backoff configured. Keep the request cycle free of it.
• Test with the package's fake or a bound stub. In feature tests, bind a fake implementation in the container ($this->app->instance(...)) or use the package's provided fake if one exists. Assert on your adapter's behavior rather than the package internals.
• Migrations and data. If the package ships migrations, publish them into your app so you own the schema history, and review them before running. On Laravel 9, anonymous migrations (return new class extends Migration) avoid class-name collisions.
• Upgrade discipline for 0.x. Pin to ^0.4.1 rather than *, commit the lockfile, and read the changelog between minors. Pre-1.0 packages may change signatures in minor releases.

Gotchas and Tips

• Laravel 9 changed the surrounding stack. Laravel 9 moved to Symfony 6 and Flysystem 3, and dropped the $dates property in favor of $casts. If the package interacts with filesystems, HTTP, or model date handling, exercise those paths explicitly after upgrading — the package's "Laravel 9 support" claim covers its own code, not your integration points.
• PHP 8.0 is the floor. Watch for deprecations around null-to-non-nullable internal parameters and dynamic properties; run your test suite with E_ALL and check storage/logs/laravel.log after the first real request.
• Version conflicts are the usual failure mode. If composer require fails, use composer why-not <vendor>/<package> 0.4.1 to find the package pinning an older illuminate/support. Laravel 9 support often requires bumping other dependencies in the same pass.
• Clear caches after upgrading. php artisan config:clear, route:clear, view:clear, and package:discover. Stale cached config is the most common reason a newly published config file appears to be ignored.
• Publish tags are not always present. If vendor:publish with a tag does nothing, run it without --tag and read the prompt, or check the provider's publishes() paths directly.
• Debugging: log the resolved config and the concrete class behind the contract (get_class(app(SomeContract::class))) at boot in a local environment. That single line distinguishes "config not loaded" from "wrong binding."
• Extension points: look for a bound interface in the provider, macroable classes, and event dispatching. Prefer extending via container rebinding and events over forking the package. If you must patch behavior, use a decorator implementing the package contract and bind it in your own AppServiceProvider.
• Re-verify on the next release. A patch-level Laravel 9 addition suggests the maintainers are catching up on framework support; confirm Laravel 10/11 compatibility separately before planning a framework upgrade.