Getting Started

This package's v2.2.12 release is a compatibility release: the only change is the addition of Laravel 12 support. That means the day-to-day developer surface is unchanged from v2.2.x — no new APIs, no deprecations, no config changes. The work it unlocks is the upgrade path: you can now install it on a Laravel 12 application without --ignore-platform-reqs or a fork.

Minimal steps:

Install / upgrade
```
composer require <vendor>/<package>:^2.2
# existing apps:
composer update <vendor>/<package> --with-all-dependencies
```
Verify resolution before touching code:
```
composer why-not <vendor>/<package> 2.2.12
```
If that reports laravel/framework 12.x, the constraint change in 2.2.12 did not land — check for a transitive dependency pinning illuminate/support to ^11.
Publish what the package ships
```
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
```
Inspect the tags first (--tag=config, --tag=migrations, --tag=assets) so you publish deliberately on an existing app rather than overwriting a tuned config file.
Where to look first, in this order:
- config/<package>.php — the real API surface for most Laravel packages; nearly every behavior toggles here.
- The service provider's register()/boot() — tells you what is bound as singleton vs. transient and what is auto-discovered.
- The facade (if one exists) — check getFacadeAccessor() to see which container key it resolves, then app('<key>') is your escape hatch in tests.
- README quickstart plus the package's own tests/ directory — the test suite is the most accurate documentation of intended usage.

First use case: get one end-to-end path green in a feature test before wiring anything into product code.

public function test_package_is_wired_up(): void
{
    $result = app(PackageContract::class)->handle('smoke');
    $this->assertNotNull($result);
}

Confirm the Laravel 12 target explicitly — check php artisan about for the framework version and confirm the package appears in the discovered package list. A silent failure here (provider not discovered) usually means a stale bootstrap/cache/packages.php.

Implementation Patterns

Prefer constructor injection over the facade. Resolve the package's contract or concrete class in the constructor so it is mockable and so you are not depending on a facade root that may be aliased differently across Laravel versions:

public function __construct(private PackageContract $package) {}

Reserve the facade for Blade templates, tinker, and quick scripts. In tests, Package::shouldReceive(...) only works if the facade's underlying binding is a singleton — check register() before relying on it.

Bind the contract in your own service provider when you need to wrap or decorate behavior. The package's binding is registered during register(), so your application provider (which boots after package discovery) can safely $this->app->extend() or rebind it. This is the primary extension point that does not require forking.

Config-driven variation, not code branches. Keep environment-specific behavior in the config file and read it through config('<package>.<key>') at call sites rather than in constructors — config is unavailable during some early package boot phases and cached thereafter.

Queue and event boundaries. Anything that crosses a queue boundary must be serializable. If a job holds the package's service object, resolve it inside handle() instead of injecting it into the job's constructor; a serialized container binding will fail to hydrate.

Migrations on an existing app. If the package ships migrations, publish them, adjust for your existing schema (table prefixes, bigIncrements vs id), and backfill before enabling any feature flag. Run them in a separate deploy step from the code deploy when the package writes to a new table.

Laravel 12 upgrade pattern for downstream apps:

composer update <vendor>/<package> laravel/framework --with-all-dependencies
php artisan config:clear && php artisan route:clear && php artisan view:clear
php artisan migrate --pretend   # if migrations changed
php artisan test

Then re-diff published config against the new stub (vendor/<vendor>/<package>/config/) — a compatibility release rarely changes config, but a stale published file masking a new key is the most common silent breakage.

CI matrix. If you maintain a package or a multi-app monorepo consuming this, the meaningful matrix is now laravel/framework: ^10, ^11, ^12 × your supported PHP versions. Since 2.2.12 only widens the constraint, a matrix row for 12 plus your existing rows is sufficient — no behavior-level test changes needed.

Test hygiene. Use RefreshDatabase where the package persists, and swap real transports for fakes in setUp() so the suite stays offline. Assert on the package's public contract, not on internals, so the next compatibility bump doesn't break your tests.

Gotchas and Tips

"Laravel 12 support" ≠ "everything works on 12." The constraint widening means the maintainers ran their suite against 12; it does not guarantee your transitive graph resolves. composer why-not and composer outdated --direct are the first two commands to run when an install fails.
Config caching bites during upgrades. After any version bump, php artisan config:clear is mandatory in local and staging. A cached config from the previous version can mask a new key with null, producing confusing runtime errors rather than an install failure.
Publishing is destructive by default. vendor:publish --force will overwrite a tuned config. Diff before forcing; in most cases you want to leave the published file alone and only add newly introduced keys.
Auto-discovery can silently skip the provider. If the package's composer.json extra.laravel.providers entry is missing or malformed, nothing errors — the facade simply resolves to nothing. php artisan package:discover re-runs discovery; bootstrap/cache/packages.php shows what was actually registered.
Facade vs. app() mismatch. Facades resolve a specific accessor key. If you rebind or extend that key in your own provider, the facade and app(Contract::class) may diverge. Bind the contract and alias the key if you rely on both.
Semver reading. v2.2.12 is a patch bump widening a dependency constraint — treat it as safe to adopt, but confirm the patch number actually matches the release you pinned. Constraint-widening releases are occasionally re-tagged; check composer show <vendor>/<package> reports 2.2.12 and not a locally cached metadata copy (composer clear-cache if in doubt).
Debugging checklist when something misbehaves after the bump: composer show <vendor>/<package> → php artisan about → php artisan package:discover → php artisan config:clear → tail storage/logs/laravel.log. That sequence resolves the large majority of "it worked on Laravel 11" reports.
Extension points, ranked by durability: (1) config, (2) container binding/extend(), (3) events the package dispatches, (4) facade macros, (5) subclassing. Reaching for (5) is a signal to open an upstream issue — it is the first thing to break on the next compatibility release, as 2.2.12 demonstrates is still an active maintenance stream.

Laravel Sql Logger Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips