Log Laravel Package

Getting Started

• composer require yiisoft/log — no framework required; it's a standalone PSR-3 implementation from the Yii3 ecosystem.
• Minimal bootstrap:

use Yiisoft\Log\Logger;
use Yiisoft\Log\Target\File\FileTarget;

$logger = new Logger();
$logger->addTarget(new FileTarget('/var/log/app.log'));

$logger->info('app started', ['pid' => getmypid()]);
$logger->flush();

• Read these three classes first, in this order: Logger (PSR-3 entry points + flush() + setFlushInterval()), Target (the abstract base — this is your extension point), and Message (the object your targets actually receive).
• First real use case: replace scattered error_log() / var_dump() calls with a single injected logger writing to a rotated file, with ERROR+ routed somewhere a human will see.

Implementation Patterns

• Type-hint Psr\Log\LoggerInterface in services. Reach for Yiisoft\Log\LoggerInterface only when you specifically need flush() or setFlushInterval().
• Register Logger as a shared singleton in your DI container and build targets from config, not inline in services. Otherwise each new Logger buffers its own messages and flushes at unpredictable times.
• Multi-target is the normal production shape:
  • dev: StreamTarget to stderr/stdout, all levels.
  • prod: FileTarget + FileRotator, WARNING+.
  • alerts: EmailTarget or SyslogTarget, ERROR+ only, via setLevels().
• Per-target level filtering (setLevels([LogLevel::ERROR, LogLevel::CRITICAL])) keeps noise down without touching call sites.
• Message formatting supports {placeholder} interpolation from the PSR-3 context array, so log calls can stay readable: $logger->error('Payment failed for {orderId}', ['orderId' => $id]).
• Custom targets: extend Target, implement export(array $messages): void. Override collect() only if you need per-message buffering (rate limits, batching to a remote API).
• Test doubles: use a StreamTarget pointed at php://memory, or a tiny in-memory Target subclass, and assert on captured Message objects rather than string-matching output.

Gotchas and Tips

• Nothing is written until flush(). This is the #1 surprise. Register register_shutdown_function(fn () => $logger->flush(true)) in your bootstrap, and call flush() in job/request teardown — otherwise a fatal error loses the messages that explain it.
• Default flush interval is ~1000 messages. In long-running workers (queues, Swoole, Octane-style runtimes) flush at job boundaries or memory climbs.
• Rotation is opt-in. A bare FileTarget grows forever; pass a FileRotator (max size, retained files) if you care about disk.
• Target::export() runs synchronously in your request. A bad path, full disk, or unwritable directory throws inside a log call — make the directory writable up front, and consider guarding custom targets in a try/catch.
• Trace capture (backtrace per message) has real cost. Don't log inside tight loops without sampling or a level gate; debug-level logging in a hot path is not free even if the target filters it later.
• log($level, ...) accepts any string per PSR-3, but Yii filters compare against LogLevel::* constants — stick to the constants or your setLevels() config won't match.
• Context values must be stringable when interpolated. Arrays and objects need a serializer in your target or they'll render as Array.
• In tests, call flush() in tearDown(); buffered messages survive across test methods if the container shares one Logger.
• Extension points worth knowing: subclass Target for new sinks, implement FileRotatorInterface for custom retention, and swap Logger behind its interface for a null-logger in benchmarks.