MonologBundle

https://github.com/symfony/monolog-bundle
Admin
MonologBundle provides seamless integration of the Monolog logging library into the Symfony...
Tokens:26,538
Snippets:143
Trust Score:9.5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Usage example for build()

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Shows how to invoke build() manually and inspect the registered compiler passes. The comment notes that LoggerChannelPass is shared with FixEmptyLoggerPass.

```php
use Symfony\Bundle\MonologBundle\MonologBundle;
use Symfony\Component\DependencyInjection\ContainerBuilder;

$container = new ContainerBuilder();
$bundle = new MonologBundle();
$bundle->build($container);

// All five passes are present; LoggerChannelPass is shared with FixEmptyLoggerPass
foreach ($container->getCompilerPassConfig()->getBeforeOptimizationPasses() as $pass) {
    // LoggerChannelPass, FixEmptyLoggerPass, AddProcessorsPass, AddSwiftMailerTransportPass...
}
```

--------------------------------

### Manual usage example of MessageFactory

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Shows how to manually instantiate MessageFactory and call createMessage. Normally the container builds the factory from swift_mailer handler config, but this is the manual equivalent.

```php
use Symfony\Bundle\MonologBundle\SwiftMailer\MessageFactory;

$factory = new MessageFactory($swiftMailer, 'sender@example.com', 'ops@example.com', 'Log alert');
$message = $factory->createMessage('The email body', [['message' => '...']]);
```

--------------------------------

### YAML configuration for swift_mailer handler

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Indirect usage example: the factory becomes the email_prototype when none is configured. Configures the swift_mailer handler with from_email, to_email, subject, content_type, and level.

```yaml
monolog:
    handlers:
        mail:
            type: swift_mailer
            from_email: 'sender@example.com'
            to_email: 'ops@example.com'
            subject: 'An error occurred'
            content_type: 'text/html'
            level: error
```

--------------------------------

### Process configuration with Processor

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Configuration.md

This example shows how to use the Configuration class with the Processor to process a configuration array. The resulting $config includes all default values, such as 'use_microseconds' => true and handler defaults like 'level' => 'DEBUG' and 'bubble' => true.

```php
use Symfony\Bundle\MonologBundle\DependencyInjection\Configuration;
use Symfony\Component\Config\Definition\Processor;

$config = (new Processor())->processConfiguration(new Configuration(), [[
    'handlers' => [
        'main' => ['type' => 'stream', 'path' => '/var/log/app.log'],
    ],
]]);
// $config = ['use_microseconds' => true, 'handlers' => ['main' => ['type' => 'stream', 'path' => ..., 'level' => 'DEBUG', 'bubble' => true, ...all defaults...]]]
```

--------------------------------

### FixEmptyLoggerPass usage example with YAML and PHP

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Shows a YAML configuration for a channel without handlers and a PHP snippet demonstrating that the pass adds a NullHandler to the logger, preventing STDERR logging on Monolog 1.

```yaml
monolog:
    channels: ['quiet']
    handlers:
        main: { type: stream, path: '%kernel.logs_dir%/app.log' }
```

```php
// monolog.logger.quiet would otherwise log to STDERR on Monolog 1; the pass adds the null handler:
$logger = $container->get('monolog.logger.quiet');
// $logger->getHandlers() === [NullHandler]
```

--------------------------------

### Error handling example for nonexistent channel

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

PHP comment showing the compile-time error thrown when a handler is assigned to a nonexistent channel. The error is InvalidArgumentException with a specific message.

```php
// Config: a handler with channels: ['missing']
// ContainerBuidler::compile() throws:
// InvalidArgumentException: Monolog configuration error: The logging channel "missing" assigned to the "main" handler does not exist.
```

--------------------------------

### Autowiring alias argument auditLogger

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

PHP constructor example showing how the tagged service receives the channel logger via autowiring. The container gains an autowiring alias argument named auditLogger.

```php
// App\AuditService gets monolog.logger.audit injected as Psr\Log\LoggerInterface
// and the container gains autowiring alias argument auditLogger:
public function __construct(private LoggerInterface $auditLogger) {}
```

--------------------------------

### Configure swift_mailer handler with custom mailer (YAML)

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Example configuration for a swift_mailer handler that uses a custom mailer id. The AddSwiftMailerTransportPass looks up the transport for the mailer id (e.g., my_custom_mailer.transport.real) and sets it on the handler.

```yaml
monolog:
    handlers:
        mail:
            type: swift_mailer
            from_email: 'a@example.com'
            to_email: 'b@example.com'
            subject: 'Log'
            mailer: my_custom_mailer   # pass looks up my_custom_mailer.transport.real etc.
```

--------------------------------

### Register DebugHandlerPass manually (PHP)

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Example of manually registering the deprecated DebugHandlerPass with a LoggerChannelPass. Emits a deprecation warning; prefer AddDebugLogProcessorPass from FrameworkBundle.

```php
use Symfony\Bundle\MonologBundle\DependencyInjection\Compiler\DebugHandlerPass;
use Symfony\Bundle\MonologBundle\DependencyInjection\Compiler\LoggerChannelPass;

$container->addCompilerPass(new DebugHandlerPass(new LoggerChannelPass()));
```

--------------------------------

### Catch InvalidConfigurationException for missing handler

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Configuration.md

This example demonstrates error handling when a 'fingers_crossed' handler is missing the 'handler' option. It catches the InvalidConfigurationException and prints the message: 'The handler has to be specified to use a FingersCrossedHandler or BufferHandler or FilterHandler or SamplingHandler'.

```php
use Symfony\Bundle\MonologBundle\DependencyInjection\Configuration;
use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
use Symfony\Component\Config\Definition\Processor;

try {
    (new Processor())->processConfiguration(new Configuration(), [[
        'handlers' => [
            'fc' => ['type' => 'fingers_crossed', 'action_level' => 'WARNING'], // missing 'handler'
        ],
    ]]);
} catch (InvalidConfigurationException $e) {
    echo $e->getMessage();
    // "The handler has to be specified to use a FingersCrossedHandler or BufferHandler or FilterHandler or SamplingHandler"
}
```

--------------------------------

### Handle Monolog configuration failures during container compilation

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/errors.md

Pre-compile a Symfony DI container with try/catch to fail gracefully at boot when optional handler SDKs are missing. Deterministic exception types: InvalidConfigurationException for config errors, InvalidArgumentException for unknown handlers/channels/processors, and RuntimeException for missing optional dependencies.

```php
use Symfony\Component\DependencyInjection\ContainerBuilder;

$container = new ContainerBuilder();
// ... register extensions ...
try {
    $container->compile();
} catch (\Symfony\Component\Config\Definition\Exception\InvalidConfigurationException $e) {
    // config problem — log and fall back
} catch (\InvalidArgumentException $e) {
    // unknown handler type / bad channel / bad processor tag
} catch (\RuntimeException $e) {
    // missing optional dependency (gelf, telegram, redis, predis, monolog < 1.26)
}
```

--------------------------------

### MessageFactory::__construct

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Constructor that initializes the MessageFactory with the Swift Mailer instance and email configuration parameters.

```APIDOC
## MessageFactory::__construct

### Description
Initializes the MessageFactory with the Swift Mailer instance and email configuration parameters.

### Method
Constructor

### Signature
```php
public function __construct(\Swift_Mailer $mailer, $fromEmail, $toEmail, $subject, $contentType = null)
```

### Parameters
- **$mailer** (\Swift_Mailer) - Required - The Swift Mailer instance used to create the message (via `createMessage()`)
- **$fromEmail** (mixed) - Required - Sender address passed to `\Swift_Message::setFrom()`
- **$toEmail** (mixed) - Required - Recipient(s) passed to `\Swift_Message::setTo()` (string or array)
- **$subject** (mixed) - Required - Subject passed to `\Swift_Message::setSubject()`
- **$contentType** (mixed) - Optional - Optional content type; applied only when non-null

### Return Value
No return value.

### Usage Example
```php
use Symfony\Bundle\MonologBundle\SwiftMailer\MessageFactory;

$factory = new MessageFactory($swiftMailer, 'sender@example.com', 'ops@example.com', 'Log alert');
```
```

--------------------------------

### MonologExtension::load() method signature

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-MonologExtension.md

Declared at MonologExtension.php:59. Loads the Monolog configuration by processing the configuration tree and registering services when handlers are configured. Returns void.

```php
/**
 * Loads the Monolog configuration.
 *
 * @param array            $configs   An array of configuration settings
 * @param ContainerBuilder $container A ContainerBuilder instance
 */
public function load(array $configs, ContainerBuilder $container)
```

--------------------------------

### PHP equivalent runtime effect of processor push

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Shows the equivalent runtime effect of the YAML tag: pushing the processor with the specified method onto the logger.

```php
// Equivalent runtime effect:
$logger->pushProcessor([new MyProcessor(), 'process']);
```

--------------------------------

### YAML configuration enabling include_stacktraces

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Declarative configuration that triggers the includeStacktraces configurator for the main handler. The path uses kernel log directory and environment.

```yaml
# config/packages/monolog.yaml
monolog:
    handlers:
        main:
            type: stream
            path: '%kernel.logs_dir%/%kernel.environment%.log'
            include_stacktraces: true
```

--------------------------------

### Constructor signature for MessageFactory

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Constructor that takes a Swift_Mailer instance, from email, to email, subject, and optional content type. The from/to/subject values are forwarded verbatim to Swift_Message setters.

```php
public function __construct(\Swift_Mailer $mailer, $fromEmail, $toEmail, $subject, $contentType = null)
```

--------------------------------

### FixEmptyLoggerPass constructor

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Constructor for FixEmptyLoggerPass, accepting a LoggerChannelPass instance that provides the list of known channels.

```php
public function __construct(LoggerChannelPass $channelPass)
```

--------------------------------

### LoggerChannelPass process method contract

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

The process method signature for LoggerChannelPass. It takes a ContainerBuilder and returns void, performing the main compilation logic.

```php
/**
 * {@inheritDoc}
 */
public function process(ContainerBuilder $container)
```

--------------------------------

### Catch InvalidConfigurationException during extension load

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/errors.md

Catch configuration validation failures thrown by MonologExtension::load() -> processConfiguration(). Use this to handle InvalidConfigurationException and read the error message from the exception.

```php
use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;

try {
    $extension->load([$myConfig], $container);
} catch (InvalidConfigurationException $e) {
    // $e->getMessage() contains one of the messages below
}
```

--------------------------------

### Direct usage of includeStacktraces

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Direct call to includeStacktraces on a StreamHandler. Safe for formatters that do not support stack traces; it becomes a no-op for others.

```php
use Monolog\Handler\StreamHandler;
use Symfony\Bundle\MonologBundle\MonologBundle;

$handler = new StreamHandler('/var/log/app.log');
MonologBundle::includeStacktraces($handler);
// If the handler uses a LineFormatter/JsonFormatter it now prints stack traces.
```

--------------------------------

### MessageFactory::createMessage

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Creates a Swift_Message template that will be used to send the log message. The body is intentionally not set; the SwiftMailerHandler fills it with the formatted content per record.

```APIDOC
## MessageFactory::createMessage

### Description
Creates a Swift_Message template that will be used to send the log message. The body is intentionally not set; the SwiftMailerHandler fills it with the formatted content per record.

### Method
createMessage

### Signature
```php
public function createMessage($content, array $records)
```

### Parameters
- **$content** (string) - Required - Formatted email body; supplied by the SwiftMailerHandler
- **$records** (array) - Required - The Monolog log records that produced the content; **ignored** by this implementation

### Return Value
\Swift_Message - A new, empty-bodied message template.

### Behavior
Calls `$this->mailer->createMessage()`, then `setTo($this->toEmail)`, `setFrom($this->fromEmail)`, `setSubject($this->subject)`, and — if a content type was configured — `setContentType($this->contentType)`. The body is intentionally not set.

### Usage Example
Indirect, through the bundle config; the factory becomes the `email_prototype` when none is configured:

```yaml
monolog:
    handlers:
        mail:
            type: swift_mailer
            from_email: 'sender@example.com'
            to_email: 'ops@example.com'
            subject: 'An error occurred'
            content_type: 'text/html'
            level: error
```

### Error Handling / Non-trivial Option
The `records` parameter is the hook a subclass could use to customize the subject per batch; the base class ignores it:

```php
class CustomMessageFactory extends MessageFactory
{
    public function createMessage($content, array $records)
    {
        $message = parent::createMessage($content, $records);
        $message->setSubject(sprintf('%s (%d records)', $this->subject, count($records)));
        return $message;
    }
}
```
```

--------------------------------

### createMessage method signature with docblock

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Method that creates a Swift_Message template. The $records parameter is ignored by this implementation but accepted for interface compatibility with SwiftMailerHandler.

```php
/**
 * Creates a Swift_Message template that will be used to send the log message
 *
 * @param string $content formatted email body to be sent
 * @param array  $records Log records that formed the content
 * @return \Swift_Message
 */
public function createMessage($content, array $records)
```

--------------------------------

### includeStacktraces(HandlerInterface $handler) method signature

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Static method that enables stack traces on a handler's formatter. Used as a service configurator when include_stacktraces is true.

```php
/**
 * @internal
 * @return void
 */
public static function includeStacktraces(HandlerInterface $handler)
```

--------------------------------

### MonologBundle::build(ContainerBuilder $container)

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Registers the bundle's compiler passes with the container. Called by the Symfony kernel during container compilation.

```APIDOC
## build(ContainerBuilder $container)

### Description
Registers the bundle's compiler passes with the container. Called by the Symfony kernel during container compilation.

### Method
build

### Parameters
#### Parameters
- **$container** (Symfony\Component\DependencyInjection\ContainerBuilder) - Required - The container being compiled

### Return
**Return type:** void

### Behavior
1. Calls `parent::build($container)`.
2. `$container->addCompilerPass($channelPass = new LoggerChannelPass())` — creates the `LoggerChannelPass` and keeps a reference.
3. `$container->addCompilerPass(new FixEmptyLoggerPass($channelPass))` — shares the same `LoggerChannelPass` instance.
4. `$container->addCompilerPass(new AddProcessorsPass())`.
5. `$container->addCompilerPass(new AddSwiftMailerTransportPass())`.

### Usage Example
```php
use Symfony\Bundle\MonologBundle\MonologBundle;
use Symfony\Component\DependencyInjection\ContainerBuilder;

$container = new ContainerBuilder();
$bundle = new MonologBundle();
$bundle->build($container);

// All five passes are present; LoggerChannelPass is shared with FixEmptyLoggerPass
foreach ($container->getCompilerPassConfig()->getBeforeOptimizationPasses() as $pass) {
    // LoggerChannelPass, FixEmptyLoggerPass, AddProcessorsPass, AddSwiftMailerTransportPass...
}
```
```

--------------------------------

### Tagging a service with monolog.logger channel audit

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

YAML configuration showing how to tag a service with the monolog.logger tag and a channel attribute. This causes the pass to create a dedicated logger for the channel and inject it into the service.

```yaml
services:
    App\AuditService:
        tags:
            - { name: monolog.logger, channel: audit }
```

--------------------------------

### Custom MessageFactory subclass overriding createMessage

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Shows how to subclass MessageFactory to customize the subject per batch using the $records parameter, which the base class ignores.

```php
class CustomMessageFactory extends MessageFactory
{
    public function createMessage($content, array $records)
    {
        $message = parent::createMessage($content, $records);
        $message->setSubject(sprintf('%s (%d records)', $this->subject, count($records)));
        return $message;
    }
}
```

--------------------------------

### YAML service definition for monolog.processor tag

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Defines a service tagged with monolog.processor, specifying the channel and method. The method attribute causes the processor to be pushed as an array [Reference(id), method].

```yaml
services:
    App\Logging\MyProcessor:
        tags:
            - { name: monolog.processor, channel: app, method: process }
```

--------------------------------

### MonologBundle::includeStacktraces(HandlerInterface $handler)

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Enables stack traces on a handler's formatter, in place. Used by the DI container as a service configurator.

```APIDOC
## includeStacktraces(HandlerInterface $handler)

### Description
Enables stack traces on a handler's formatter, in place. Used by the DI container as a service configurator.

### Method
includeStacktraces

### Parameters
#### Parameters
- **$handler** (Monolog\Handler\HandlerInterface) - Required - The handler whose formatter should include stack traces

### Return
**Return type:** void

### Behavior
Reads `$handler->getFormatter()`. If the formatter is an instance of `Monolog\Formatter\LineFormatter` or `Monolog\Formatter\JsonFormatter`, calls `$formatter->includeStacktraces()`. Other formatter types are silently ignored.

### Usage Example
```php
use Monolog\Handler\StreamHandler;
use Symfony\Bundle\MonologBundle\MonologBundle;

$handler = new StreamHandler('/var/log/app.log');
MonologBundle::includeStacktraces($handler);
// If the handler uses a LineFormatter/JsonFormatter it now prints stack traces.
```

### Error Handling
The call is safe for formatters that do not support stack traces (e.g. `Monolog\Formatter\NormalizerFormatter`): the instanceof checks make the method a no-op, so it may be attached as a configurator to any handler type without risking a fatal error.
```

--------------------------------

### build(ContainerBuilder $container) method signature

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Overrides the build method to register compiler passes. Called by the Symfony kernel during container compilation.

```php
/**
 * @return void
 */
public function build(ContainerBuilder $container)
```

--------------------------------

### LoggerChannelPass class declaration

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Declares the LoggerChannelPass class implementing CompilerPassInterface. This is the main compiler pass that creates per-channel logger services and wires handlers.

```php
class LoggerChannelPass implements CompilerPassInterface
```

--------------------------------

### Class declaration for MonologExtension

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-MonologExtension.md

Declares the MonologExtension class extending Symfony's Extension. Marked @final since 3.9.0.

```php
class MonologExtension extends Extension
```

--------------------------------

### Class declaration for MessageFactory

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/SwiftMailer-MessageFactory.md

Declares the MessageFactory class in the Symfony\Bundle\MonologBundle\SwiftMailer namespace. This class is instantiated lazily by MonologExtension::buildHandler() for the swift_mailer handler type.

```php
class MessageFactory
```

--------------------------------

### MonologBundle class declaration

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/MonologBundle.md

Declares the MonologBundle class, extending Symfony's Bundle class. Marked @final since 3.9.0.

```php
class MonologBundle extends Bundle
```

--------------------------------

### FixEmptyLoggerPass class declaration

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

Declares the FixEmptyLoggerPass class implementing CompilerPassInterface. This pass ensures every logger has at least one handler by adding a NullHandler when none are configured.

```php
class FixEmptyLoggerPass implements CompilerPassInterface
```

--------------------------------

### Deprecated DebugHandlerPass class declaration (PHP)

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Compiler-Passes.md

The DebugHandlerPass class is deprecated since version 2.12 and will be removed in 4.0. Use AddDebugLogProcessorPass in FrameworkBundle instead.

```php
/**
 * @deprecated since version 2.12, to be removed in 4.0. Use AddDebugLogProcessorPass in FrameworkBundle instead.
 */
class DebugHandlerPass implements CompilerPassInterface
```

--------------------------------

### Validation rule for fingers_crossed handler

Source: https://github.com/symfony/monolog-bundle/blob/4.x/_autodocs/api-reference/DependencyInjection-Configuration.md

This validation rule ensures that a 'fingers_crossed' handler type has a 'handler' specified. If not, it throws an InvalidConfigurationException with the message 'The handler has to be specified to use a FingersCrossedHandler or BufferHandler or FilterHandler or SamplingHandler'.

```php
->validate()
    ->ifTrue(function ($v) { return 'fingers_crossed' === $v['type'] && empty($v['handler']); })
    ->thenInvalid('The handler has to be specified to use a FingersCrossedHandler or BufferHandler or FilterHandler or SamplingHandler')
->end()
```
Tokens:
Raw