Logger

The logger class uses static method to setup and create logs and wrapps the monolog logger instance as internal property which handles the main logging process by its known handlers.

The Logger class is compatible with all PHP LOG_* levels, Monolog levels and PSR levels, which is possible by an internal translation function that translates and checks the given level.

How to use

Default Logfiles

The default setup logs to the filessystem in to the following logfiles:

Logfile	Content	Level
error.log	All errors (including Frontend, Cron, Daemon	ERROR
web.log	Log for Frontend page calls	XF_LOG_LEVEL (Default: ERROR)
console.log	Log for Console operations	XF_LOG_LEVEL (Default: ERROR)
cron.[name].log	Log for specific Cron Jobs	XF_LOG_LEVEL (Default: ERROR) or Custom Cron Level
daemon.[name].log	Log for specific Daemons	XF_LOG_LEVEL (Default: ERROR) or Custom Daemon Level

Note: If the system is operated in the XELOS Development Mode the XF_LOG_LEVEL default is raised to WARNING

General Logging

The logger provides one method for each log level, which is more recommended than use the Logger::log(). Each of the log methods provides also a context array argument, which can be used to add detailed information that relates to the log message.

Logger::info('Unable to create toast, because of missing power supply.', [
    'device' => $device,
    'location' => $location
]);  

In additional the context can be used, to replace parts in the log message with information from the given context array.

Logger::error('Unable to connect to server {uri} with user {user}.', [
    'uri' => $uri,
    'user' => $user
]);

Debugging

Frontend

For debugging purposes you can use the debug method of the Logger class (Logger::debug(..)), which creates logs with level DEBUG. The default level is of logging for development is NOTICE / INFO, so for seeing the debug logs, the debug level must be increased to DEBUG level.

Console

The console application has a separate verbosity level which can be set by using the following verbosity flags. The level of the verbosity depends on the count of the verbosity flags -v, -vv, -vvv. The default level here is NOTICE. Important information which need to be displayed should be logged with NOTICE - this level is only intended for important information which are not an error or warning.

Verbosity	Level + E	Format
none	NOTICE	Short
-v	INFO	Extended (incl. Timestamp)
-vv	DEBUG + E_ERROR	Extended (incl. Timestamp)
-vvv	DEBUG + E_ERROR + E_WARNING + E_PARSE + E_NOTICE	Extended (incl. Timestamp)

Technical Description

The Logger functionality depends on the monolog vendor library which is wrapped by the XELOS Logger class. But the Logger can be used before monolog and other dependencies are loaded because of a deferred setup and logging mechanism. The setups and logs are retained until the dependencies are loaded and flushes all setups and logs after the first logging call when monolog is available.

Setup the Logger

The logger does not know about a specific setup, it uses the given factories to create and add a bundle of stream handlers, which are pushed to the internal monolog logger instance. This keeps the xelos logger more flexible for different setups based on its environment.

Stream factories

There are two abstract stream handler factories which one of them should be used to implement a factory. The StreamHandlerFactory ist the plain factory which expects only a log level to create its stream handler. The StreamResourceHandlerFactory is a resource based factory which in addition expects a resource that is used for writing logs.

DefaultStreamHandlerFactory

Created a new instance of a default handler that logs to the given resource which can be a file path or a open resource like STDOUT etc.

ThreadedStreamHandlerFactory

Created a new instance of a resource based stream handler that considers the pid and thread caption on each log entry.

NativeMailStreamHandlerFactory

Creates a non resource based stream handler that uses the monolog provided native stream handler which uses the native php mail function for sending mails.

DatabaseStreamHandlerFactory

Creates a non resource xelos custom DatabaseStreamHandler for logging into the database.

DisplayStreamHandlerFactory

Creates a xelos custom stream handler which outputs the logs directly to the user in debug mode.

Setup routine

The setup of the logger is very flexible which allows a different setup at different application entry points like daemon, cron, console and frontend. The logger provides the static function Logger::setup(array $factories), which can be use multiple time for setting up via new factories. The first call of this setup method initializes the internal monolog logger and creates all stream handlers by given factories. Each further call of this method setups only the stream handlers by given factories.

The setup method expects an array of stream handler factory instances as first parameter. Each containing factory instance can be named by a custom string as array key which can be used for accessing the stream handler later. Each factory uses the XF_LOG_LEVEL by default if no explicit level is set.

Logger::setup([
  'frontend.file' => new DefaultStreamHandlerFactory('path/to/log', Logger::INFO),
  'mail' => new NativeMailStreamHandlerFactory(Logger::CRITICAL)      
]);