Terry Api Laravel Package

Getting Started

• Install the release that widened the constraint. composer require <vendor>/<package>:^0.8.1. The only change in v0.8.1 is that psr/log now accepts ^1 || ^2 || ^3 (previously narrower), so this release is what makes the package installable alongside newer Laravel/Monolog stacks. If you were pinned to an older tag because of a psr/log conflict, this is the version to move to.
• Look first at the service provider and any published config. That is where the LoggerInterface binding, channel mapping, and processor registration will live. Run php artisan vendor:publish --provider="...ServiceProvider" if a config file is offered, and read the binding before reading the internals.
• Confirm your resolved PSR-3 version. composer show psr/log and composer why psr/log. On Laravel 9+ you will typically resolve psr/log 3.x via Monolog 3; on older stacks you may still be on 1.x/2.x. Both are now legal for this package, but they are not the same interface (see Gotchas).
• First use case: inject Psr\Log\LoggerInterface into a controller or queued job, log a message with a context array, and confirm it lands in storage/logs/laravel.log and honours LOG_CHANNEL. That single test proves the binding, the channel routing, and the PSR-3 bridge all work on your stack.

Implementation Patterns

• Depend on the interface, not the facade, in domain code. Keep Log:: at the application edges (middleware, console commands, service providers) and inject LoggerInterface into services, actions, and jobs. This is the main day-to-day payoff: your code stays framework-agnostic and testable, and the package's binding decides where records actually go.
• Channel-per-domain routing. If the package supports a channel map in config, define one channel per bounded context (payments, sync, audit) rather than one global logger. Route by binding a contextualised logger per service, or by resolving Log::channel('payments') and passing it in as the LoggerInterface.
• Structured context, not string interpolation. Pass ['order_id' => $id, 'attempt' => $n] as the context array; reserve the message for the human-readable event name. This is what makes the output searchable and what survives a swap of the underlying handler.
• Request-scoped context via middleware. Generate a request/correlation ID in middleware and attach it to every record for that request. If the package exposes processors (Monolog pushProcessor / a withContext-style API), register it once there instead of threading the ID through every call site.
• Re-establish context in queue workers. Workers are long-lived; context pushed in one job leaks into the next. Push at the start of handle() and pop/reset in a finally, or scope the contextual logger to the job only.
• Testing pattern: rebind LoggerInterface to a spy or Psr\Log\NullLogger in the test container. Assert on the records (level, message, context keys) rather than on log file contents — that is the whole reason to type-hint the interface.
• Upgrade pattern for the constraint change. When bumping to v0.8.1, use composer update <vendor>/<package> psr/log --with-dependencies so the lockfile actually re-resolves; a plain composer update may leave you on the old PSR-3 pin and hide the benefit.

Gotchas and Tips

• v0.8.1 is a compatibility release, not a feature release. Behaviour is unchanged; it only relaxes a constraint. Do not schedule a regression pass expecting new API — but do treat it as the version that unlocks installs on newer Laravel.
• PSR-3 2.x and 3.x are not source-compatible with 1.x. If the package (or your own code) implements LoggerInterface rather than just consuming it, the signatures differ: 2.x added void return types and typed array $context; 3.x widened $message to string|\Stringable. An implementation written against ^1 will fatal or fail an interface check once Composer resolves 2/3. Widening the constraint only helps if the implementation was already updated.
• A widened constraint is not a guarantee. Something else in your tree (an SDK, an older Monolog bridge, a legacy bundle) can still pin psr/log to ^1. Diagnose with composer why-not psr/log ^3 before assuming the package is at fault.
• Stringable in messages only works on PSR-3 3.x. If you rely on passing objects with __toString as $message, it will be rejected or mishandled on a 1.x/2.x resolution. Cast explicitly to (string) if you need to support both.
• Config caching bites. If channel maps or processors are read from config, run php artisan config:cache (and config:clear while debugging) — a stale cached config is the most common "my new channel doesn't log" cause.
• Never log the same exception twice. If the package registers a global exception handler that logs, your own report()/catch logging will duplicate records. Pick one owner per failure path.
• Extension points to check, in order: the container binding for LoggerInterface, any channel-resolver or processor hook in the config, and the published config file itself. Rebinding the interface in a test or a tenancy package is the cleanest way to redirect output without touching call sites.
• Treat the logger as an external boundary in tests. Asserting on exact formatted lines couples your suite to Monolog's formatter, which changes between Monolog 2 and 3 — assert on PSR-3 records instead.