README

!! THIS PACKAGE IS NO LONGER MAINTAINTED, use eth8505/laminas-monolog instead !!

Eth8505\Monolog - ZF3 module integrating monolog with zend framework v3

The Eth8505\Monolog module integrates monolog/monolog as a zf3-module via zendframework/zend-servicemanager.

How to install

⚠️ Please note that this package requires at least php 7.1.
Install eth8505/zf3-monolog package via composer.

$ composer require eth8505/zf3-monolog

Load the module in your application.config.php file like so:

<?php

return [
	'modules' => [
		'Eth8505\\Monolog',
		// ...
	],
];

How to use

In your application config (usually located in config/autoload/monolog.global.php), specify your monolog in the monolog/loggers key.

Configuring loggers

Each key (Log\MyApp in the sample code) can contain a separate logger config and is available directly via the service manager.

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default'
            ]
        ]
    ]
];

Each logger config is available direcly via the service manager.

$logger = $container->get('Log\MyApp');

Adding log handlers

Multiple handlers can be added to a logger config via the handlers key.

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default',
                'handlers' => [
                    'stream' => [
                        'name' => StreamHandler::class,
                        'options' => [
                            'path'   => 'data/log/myapp.log',
                            'level'  => Logger::DEBUG
                        ],
                    ],
                    'fire_php' => [
                        'name' => ChromePHPHandler:class
                    ]
                ]
            ]
        ]
    ]
];

Using formatters

Each handler can be configured with a formatter in order to specify a specific format. This can be useful whenlogging to logstash for example.

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default',
                'handlers' => [
                    'stream' => [
                        'name' => StreamHandler::class,
                        'options' => [
                            'path'   => 'data/log/myapp.log',
                            'level'  => Logger::DEBUG
                        ],
                        'formatter' => [
                            'name' => LogstashFormatter::class,
                            'options' => [
                                'applicationName' => 'myApp',
                                'systemName' => gethostname()
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ]
];

Using processors

Processors can be used to enrich the logged data with additional data. The WebProcessor can for example be used to add the request URI and client IP to the log record.

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default'
                'processors' => [
                    WebProcessor::class
                ]
            ]
        ]
    ]
];

Special syntax

When configuring handlers, formatters or processors, you can either specify a class name in string (or ::class constant) format

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default'
                'processors' => [
                    WebProcessor::class
                ]
            ]
        ]
    ]
];

or alternatively in name/options array notation, where the options are translated into the respective classes constructor parameters by using Reflection based Named parameters.

return [
    'monolog' => [
        'loggers' => [
            'Log\MyApp' => [
                'name' => 'default'
                'processors' => [
                    [
                        'name' => WebProcessor::class,
                        'options' => [
                            'extraFields' => [
                                'url' => 'REQUEST_URI',
                                'http_method' => 'REQUEST_METHOD',
                                'server' => 'SERVER_NAME'
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ]
];

Custom handlers, processors and formatters

Since this module creates everything via the service manager using plugin managers, custom handlers, processors and formatters can be easily registered, by adding them to the respective config keys

return [
    'monolog' => [
        'formatters' => [
            factories' => [
                MyCustomFormatter::class => MyCustomFormatterFactory::class
            ]
        ],
        'handlers' => [
            'factories' => [
                MyCustomHandler::class => MyCustomHandlerFactory::class
            ]
        ],
        'processors' => [
            'factories' => [
                MyCustomProcessor::class => MyCustomProcessorFactory::class
            ]
        ]
    ]
];

⚠️ Note that only formatters using custom factories need to be explicitly registered. Any other handler configured will be automatically created using the internal, reflection-based factories.

Extending log handlers

You can define default loggers and inherit from them in other loggers.

return [
    'monolog' => [
        'loggers' => [
            'base' => [
                // default logger config
            ],
            'inherited' => [
                '@extends' => 'base'
            ]
        ]
    ]
];

ℹ️ Even though recursion is supported here as of Version 1.0.3, it is limited to 10 levels and will throw a Eth8505\Monolog\Exception\RuntimeException if recursed any deeper.

See example config for details.

Thanks

Thanks to neckeloo and his Monolog Module and enlitepro for their Enlite Monolog as they served as a template for this module.

eth8505 / zf3-monolog

Maintainers

Details