Installation

To install the Logger component, you will need to use Composer. Run the following command in your terminal:

composer require runopencode/logger

This will download and install the Logger component along with its dependencies.

Basic setup

In your project, you will need to initialize the Logger by wrapping an existing PSR-3 logger implementation:

 1 <?php
 2
 3 declare(strict_types=1);
 4
 5 use Psr\Log\LogLevel;
 6 use RunOpenCode\Component\Logger\Logger;
 7 use Monolog\Logger as MonologLogger;
 8 use Monolog\Handler\StreamHandler;
 9
10 // Create your PSR-3 logger (using Monolog as an example)
11 $psrLogger = new MonologLogger('app');
12 $psrLogger->pushHandler(new StreamHandler('/path/to/logs/app.log', LogLevel::DEBUG));
13
14 // Wrap it with RunOpenCode Logger
15 $logger = new Logger(
16     decorated: $psrLogger,
17     contextProviders: [],           // Optional: context providers
18     debug: false,                    // Optional: debug mode (default: false)
19     defaultLevel: LogLevel::CRITICAL // Optional: default log level (default: CRITICAL)
20 );

The Logger component is a decorator that wraps any PSR-3 logger implementation and adds additional functionality on top of it.

Using the interface

It is highly recommended to use the LoggerInterface from this component as a dependency in your classes, rather than the concrete implementation:

 1 <?php
 2
 3 declare(strict_types=1);
 4
 5 namespace App\Service;
 6
 7 use RunOpenCode\Component\Logger\Contract\LoggerInterface;
 8
 9 final readonly class UserService
10 {
11     public function __construct(private LoggerInterface $logger)
12     {
13         // noop.
14     }
15
16     public function deleteUser(int $userId): void
17     {
18         try {
19             $this->repository->delete($userId);
20         } catch (\Throwable $exception) {
21             $this->logger->exception(
22                 $exception,
23                 'Failed to delete user',
24                 ['user_id' => $userId]
25             );
26             // ...
27         }
28     }
29 }

The LoggerInterface extends PSR-3’s LoggerInterface and adds the exception() and throw() methods for convenient exception logging.

Debug mode

When creating a Logger instance, you can enable debug mode. In debug mode, the exception() method will throw the exception after logging it, which is useful during development:

 1 <?php
 2
 3 use Psr\Log\LogLevel;
 4 use RunOpenCode\Component\Logger\Logger;
 5
 6 // In development environment
 7 $logger = new Logger(
 8     decorated: $psrLogger,
 9     debug: true  // Exceptions will be thrown after logging
10 );
11
12 // In production environment
13 $logger = new Logger(
14     decorated: $psrLogger,
15     debug: false  // Exceptions will only be logged, not thrown
16 );

This allows you to use the same code in both development and production environments, with exceptions being thrown in development for easier debugging and only logged in production for graceful error handling.

Default log level

You can configure the default log level for exception logging. This level is used when you call exception() or throw() without specifying a log level:

 1 <?php
 2
 3 use Psr\Log\LogLevel;
 4 use RunOpenCode\Component\Logger\Logger;
 5
 6 $logger = new Logger(
 7     decorated: $psrLogger,
 8     defaultLevel: LogLevel::ERROR  // Use ERROR instead of CRITICAL
 9 );
10
11 // This will log at ERROR level
12 $logger->exception($exception);
13
14 // You can still override it per-call
15 $logger->exception($exception, level: LogLevel::CRITICAL);

The default log level is LogLevel::CRITICAL if not specified.

Symfony integration

If you are using Symfony framework, you should use the runopencode/logger-bundle package which automatically registers the Logger as a service in your container and provides configuration options.

See the Logger Bundle documentation for more information about Symfony integration.