Logger Laravel Package

Getting Started

Start by installing via Composer (composer require spiral/logger) and familiarizing with the LogFactory class—the core service responsible for creating and configuring logger instances. The package provides a minimal PSR-3 compliant logging interface with added extensibility via global listeners and structured formatting.

For first-time use, inject LogFactory into your service or bootstrapper, then call $factory->create('channel') to get a logger instance. If a channel logger fails to resolve (e.g., due to misconfiguration), the package now falls back to the manually assigned logger (if one exists) instead of throwing an exception. Check src/LogFactory.php and src/Logger.php for details on channel configuration and fallback behavior.

Implementation Patterns

• Channel-based isolation: Use named channels (e.g., auth, http, batch) to group logs logically. Each channel can be independently configured via the factory or config. If a channel logger fails to resolve, the package now gracefully falls back to a manually assigned logger (e.g., the default channel or a fallback instance).
• Global listeners: Attach shared behavior (e.g., JSON formatting, context enrichment) using LogFactory::addGlobalListener(). Listeners must implement Spiral\Logger\ListenerInterface. Note that listeners are applied globally, so ensure they handle fallback scenarios if needed.
• Context injection: Pass contextual data (user ID, request ID) as the second argument to log methods ($logger->info('User logged in', ['user_id' => $id])). The package ensures these are carried through the listener chain, even during fallback resolution.
• Manual logger assignment: Explicitly set a fallback logger using LogFactory::setFallbackLogger() or LogFactory::setDefaultLogger(). This logger will be used if channel-specific loggers cannot be resolved.
• Integration with Spiral Framework: If used in a Spiral app, the package integrates with the framework’s service locator and config system (config/logger.php), enabling DI and config overrides. Fallback behavior is particularly useful in dynamic environments where channel configurations may fail.

Gotchas and Tips

• Late configuration: Global listeners are applied after logger instance creation. If you add a listener after calling create(), existing instances won’t inherit it. Always configure listeners before fetching loggers. Fallback loggers are also subject to this timing constraint.
• Read-only split: Since this is a subtree split (originally from spiral/framework), avoid expecting new features—only bug fixes. Prefer using spiral/framework if full logger integration (e.g., with HTTP or CLI stacks) is needed.
• Missing default handler setup: The factory does not auto-configure handlers by default. You may need to set one via LogFactory::setHandler() (e.g., new StreamHandler('php://stderr')) or use framework defaults. Fallback loggers should also be explicitly configured with handlers.
• Context serialization: Unserializable objects in context (e.g., closures, resources) may cause silent failures. Always enforce scalar/array-only context or register a transformer listener. Fallback loggers may not handle context serialization differently, so validate this behavior explicitly.
• Test mode tip: For unit tests, use a NullHandler or custom listener that appends messages to an array, then assert against it. This avoids side effects while validating logging behavior, including fallback scenarios.
• Fallback logger behavior: The new fallback mechanism (introduced in v1.2.2) ensures that if a channel logger cannot be resolved, the manually assigned logger (e.g., default or fallback) is used instead of throwing an exception. This is useful for graceful degradation but requires explicit configuration of fallback loggers. Ensure your tests account for this behavior, especially in edge cases where channel configurations might fail.