Usage

The Logger component provides a decorator for PSR-3 loggers with additional methods specifically designed for exception handling. This document covers the main usage patterns and features.

Exception logging

The primary feature of this component is the ability to log exceptions with a clean API. The component provides two methods for exception logging:

• exception() - Logs the exception but does not throw it (unless in debug mode)

• throw() - Logs the exception and always throws it

exception() method

Use the exception() method when you want to log an exception and handle it gracefully without re-throwing it:

<?php

declare(strict_types=1);

namespace App\Service;

use RunOpenCode\Component\Logger\Contract\LoggerInterface;

final readonly class OrderService
{
    public function __construct(private LoggerInterface $logger)
    {
        // noop.
    }

    public function placeOrder(Order $order): OrderResult
    {
        try {
            $this->validateOrder($order);
            $this->processPayment($order);
            $this->notifyCustomer($order);

            return OrderResult::success($order);
        } catch (\Throwable $exception) {
            // Log the exception with context
            $this->logger->exception(
                $exception,
                'Order placement failed',
                [
                    'order_id' => $order->getId(),
                    'customer_id' => $order->getCustomerId(),
                    'total' => $order->getTotal(),
                ]
            );

            return OrderResult::failure($exception->getMessage());
        }
    }
}

In the example above, when an exception occurs, it is logged with additional context, but the method returns a failure result instead of crashing. This is useful for non-critical operations where you want to continue execution.

throw() method

Use the throw() method when you want to log an exception and then re-throw it:

<?php

public function criticalDatabaseOperation(): void
{
    try {
        $this->database->execute('CRITICAL_OPERATION');
    } catch (\Exception $exception) {
        // Log and re-throw
        $this->logger->throw(
            $exception,
            'Critical database operation failed',
            ['operation' => 'CRITICAL_OPERATION']
        );
    }
}

This is useful when you need to log the exception with context but still want the exception to propagate up the call stack.

Custom messages

Both methods accept an optional custom message parameter. If provided, this message will be used for logging instead of the exception’s message:

<?php

try {
    $this->externalApi->call();
} catch (\Throwable $exception) {
    // Use a custom message for logging
    $this->logger->exception(
        $exception,
        'External API call failed - retrying later'
    );
}

If no custom message is provided, the exception’s message will be used.

Log levels

You can specify the log level for each exception:

<?php

use Psr\Log\LogLevel;

try {
    $this->cache->clear();
} catch (\Throwable $exception) {
    // Log at WARNING level instead of the default CRITICAL
    $this->logger->exception(
        $exception,
        'Cache clear failed',
        level: LogLevel::WARNING
    );
}

If no level is specified, the logger will use the default level configured during initialization (which defaults to LogLevel::CRITICAL).

Context enrichment

The exception() and throw() methods automatically add the exception object to the log context under the exception key:

<?php

$this->logger->exception(
    $exception,
    'Operation failed',
    ['user_id' => 123]
);

// The actual context passed to the underlying PSR-3 logger will be:
// [
//     'user_id' => 123,
//     'exception' => $exception - Automatically added
// ]

This ensures that the exception object is always available in the log context for further processing by your logging infrastructure (e.g., Sentry, error tracking services, etc.).

Additionally, if you have configured context providers (see Context providers), they will automatically enrich the context with additional information.

PSR-3 compatibility

The Logger component fully implements PSR-3’s LoggerInterface, so you can use all standard PSR-3 methods:

<?php

use Psr\Log\LogLevel;

// Standard PSR-3 methods work as expected
$logger->emergency('System is down');
$logger->alert('Database connection lost');
$logger->critical('Critical error occurred');
$logger->error('An error occurred');
$logger->warning('Warning: deprecated method used');
$logger->notice('User logged in');
$logger->info('Operation completed successfully');
$logger->debug('Debug information');

// Generic log method
$logger->log(LogLevel::INFO, 'Custom log message', ['key' => 'value']);

All these methods are forwarded to the underlying PSR-3 logger that was passed to the Logger constructor. If context providers are configured, they will also enrich the context for these standard PSR-3 methods.

Debug mode behavior

The behavior of the exception() method changes based on the debug mode:

<?php

use RunOpenCode\Component\Logger\Logger;

// Production mode (debug = false)
$logger = new Logger($psrLogger, debug: false);

try {
    throw new \RuntimeException('Test exception');
} catch (\Throwable $exception) {
    // This will log the exception but NOT throw it
    $logger->exception($exception);

    // Execution continues here
    echo "Exception was logged, continuing execution...";
}

// Development mode (debug = true)
$logger = new Logger($psrLogger, debug: true);

try {
    throw new \RuntimeException('Test exception');
} catch (\Throwable $exception) {
    // This will log the exception AND throw it again
    $logger->exception($exception);

    // This line will NOT be reached
    echo "This will never be printed";
}

This allows you to use the same code in both environments, with different behavior based on the debug flag. In production, you can log exceptions and handle them gracefully, while in development, exceptions are still thrown so you can see stack traces and debug issues.

Note that the throw() method always re-throws the exception regardless of the debug mode.

Working with context

You can pass any additional context data when logging exceptions:

<?php

try {
    $this->api->updateUser($userId, $data);
} catch (\Throwable $exception) {
    $this->logger->exception(
        $exception,
        'User update failed',
        [
            'user_id' => $userId,
            'request_data' => $data,
            'timestamp' => time(),
            'ip_address' => $_SERVER['REMOTE_ADDR'] ?? 'unknown',
        ]
    );
}

The context array can contain any data that will help you debug the issue. This data is passed to the underlying PSR-3 logger and can be processed by your log handlers (e.g., written to files, sent to log aggregation services, etc.).

For automatically enriching context across all log calls, see Context providers.