Getting Started

Install the package with Composer, targeting the new major/minor line: composer require vendor/package:^2.1. Confirm your app is on Laravel 12 (or a supported version) and PHP 8.2+ before upgrading.
Look first at the package’s service provider, config file, and README examples. If the package publishes assets, run:
```
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
```
Then review config/package.php and run any required migrations.
First use case: resolve the package’s main service from Laravel’s container inside a controller, job, or command rather than instantiating it manually:
```
public function __invoke(YourPackageService $service)
{
    return $service->handle($request->validated());
}
```
This validates package discovery, configuration, and your Laravel 12 compatibility in one pass.

Implementation Patterns

Prefer constructor injection in controllers, jobs, commands, and listeners. It keeps the package’s dependencies explicit and makes tests easier to fake.
Keep environment-specific package settings in config/package.php and reference them through config('package.key'). Run php artisan config:cache in deployment after verifying the values.
Wrap package calls behind a small application service or action class. That gives you one place to adapt if the package’s API changes and keeps package-specific types out of your domain code.
For long-running package operations, dispatch a queued job and let the package run inside the worker. This is especially useful for integrations that perform HTTP calls, file processing, or third-party synchronization.
Use Laravel’s container bindings for package interfaces when the package exposes contracts. Bind them in your AppServiceProvider or a dedicated provider so you can swap implementations in tests.
In tests, use RefreshDatabase if the package ships migrations, and fake external dependencies with Laravel’s Http::fake(), Queue::fake(), or Event::fake() as appropriate. Assert the package’s observable behavior rather than internal calls.
When upgrading to v2.1.0, run the full test suite and check for deprecation notices. The Laravel 12 support is the main compatibility change; the larastan/larastan removal is development-tooling related, not runtime behavior.

Laravel 12 support does not mean every older Laravel version is supported by v2.1.0. Check the package’s composer.json constraints and keep older applications on the previous compatible line.
larastan/larastan was removed from the package’s development dependencies. This should not affect runtime use, but if your project relied on it being installed transitively, add it explicitly to your own require-dev and CI setup.
If package discovery is enabled, you normally do not need to register the provider manually. If the package does not appear to load, check composer dump-autoload, bootstrap/cache/packages.php, and the package’s extra.laravel.providers entry.
After publishing config or changing environment variables, clear cached config with php artisan config:clear. Many “package ignores my config” issues are stale config cache issues.
Avoid resolving package services directly inside config files or early bootstrap code. Resolve them from providers, controllers, jobs, or commands where the container is fully booted.
Use the package’s extension points—container bindings, config-driven drivers, macros, or published config—before forking or subclassing internals. Published config is usually the safest override surface.
Pin the package version in composer.json and upgrade deliberately in CI. Since v2.1.0 adds Laravel 12 support and removes a dev dependency, a lockfile update plus a full test run is the safest upgrade path.