Fr3nch13/CakePHP Utilities

Log
in package

Application

uses StaticConfigTrait

Logs messages to configured Log adapters. One or more adapters can be configured using Cake Logs's methods. If you don't configure any adapters, and write to Log, the messages will be ignored.

Configuring Log adapters

You can configure log adapters in your applications config/app.php file. A sample configuration would look like:

Log::setConfig('my_log', ['className' => 'FileLog']);

You can define the className as any fully namespaced classname or use a short hand classname to use loggers in the App\Log\Engine & Cake\Log\Engine namespaces. You can also use plugin short hand to use logging classes provided by plugins.

Log adapters are required to implement Psr\Log\LoggerInterface, and there is a built-in base class (Cake\Log\Engine\BaseLog) that can be used for custom loggers.

Outside of the className key, all other configuration values will be passed to the logging adapter's constructor as an array.

Logging levels

When configuring loggers, you can set which levels a logger will handle. This allows you to disable debug messages in production for example:

Log::setConfig('default', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => ['error', 'critical', 'alert', 'emergency']
]);

The above logger would only log error messages or higher. Any other log messages would be discarded.

Logging scopes

When configuring loggers you can define the active scopes the logger is for. If defined, only the listed scopes will be handled by the logger. If you don't define any scopes an adapter will catch all scopes that match the handled levels.

Log::setConfig('payments', [
    'className' => 'File',
    'scopes' => ['payment', 'order']
]);

The above logger will only capture log entries made in the payment and order scopes. All other scopes including the undefined scope will be ignored.

Writing to the log

You write to the logs using Log::write(). See its documentation for more information.

Logging Levels

By default Cake Log supports all the log levels defined in RFC 5424. When logging messages you can either use the named methods, or the correct constants with write():

Log::error('Something horrible happened');
Log::write(LOG_ERR, 'Something horrible happened');

Logging scopes

When logging messages and configuring log adapters, you can specify 'scopes' that the logger will handle. You can think of scopes as subsystems in your application that may require different logging setups. For example in an e-commerce application you may want to handle logged errors in the cart and ordering subsystems differently than the rest of the application. By using scopes you can control logging for each part of your application and also use standard log levels.

Properties

$_config : array<string, mixed>: Configuration sets.
$_dirtyConfig : bool: Internal flag for tracking whether configuration has been changed.
$_dsnClassMap : array<string, string>: An array mapping url schemes to fully qualified Log engine class names
$_levelMap : array<string, int>: Log levels as detailed in RFC 5424 https://tools.ietf.org/html/rfc5424
$_levels : array<string|int, string>: Handled log levels
$_registry : LogEngineRegistry: LogEngineRegistry class

Methods

alert() : bool: Convenience method to log alert messages
configured() : array<string|int, string>: Returns an array containing the named configurations
critical() : bool: Convenience method to log critical messages
debug() : bool: Convenience method to log debug messages
drop() : bool: Drops a constructed adapter.
emergency() : bool: Convenience method to log emergency messages
engine() : LoggerInterface|null: Get a logging engine.
error() : bool: Convenience method to log error messages
getConfig() : mixed|null: Reads existing configuration.
getConfigOrFail() : mixed: Reads existing configuration for a specific key.
getDsnClassMap() : array<string, string>: Returns the DSN class map for this class.
info() : bool: Convenience method to log info messages
levels() : array<string|int, string>: Gets log levels
notice() : bool: Convenience method to log notice messages
parseDsn() : array<string, mixed>: Parses a DSN into a valid connection configuration
reset() : void: Reset all the connected loggers. This is useful to do when changing the logging configuration or during testing when you want to reset the internal state of the Log class.
setConfig() : void: This method can be used to define logging adapters for an application or read existing configuration.
setDsnClassMap() : void: Updates the DSN class map for this class.
warning() : bool: Convenience method to log warning messages
write() : bool: Writes the given message and type to all the configured log adapters.
_init() : void: Initializes registry and configurations
_loadConfig() : void: Load the defined configuration and create all the defined logging adapters.

$_config

Configuration sets.


    protected
    static    array<string, mixed>
    $_config
     = []

$_dirtyConfig

Internal flag for tracking whether configuration has been changed.


    protected
    static    bool
    $_dirtyConfig
     = false

$_dsnClassMap

An array mapping url schemes to fully qualified Log engine class names


    protected
    static    array<string, string>
    $_dsnClassMap
     = ['console' => \Cake\Log\Engine\ConsoleLog::class, 'file' => \Cake\Log\Engine\FileLog::class, 'syslog' => \Cake\Log\Engine\SyslogLog::class]

$_levelMap

Log levels as detailed in RFC 5424 https://tools.ietf.org/html/rfc5424


    protected
    static    array<string, int>
    $_levelMap
     = ['emergency' => LOG_EMERG, 'alert' => LOG_ALERT, 'critical' => LOG_CRIT, 'error' => LOG_ERR, 'warning' => LOG_WARNING, 'notice' => LOG_NOTICE, 'info' => LOG_INFO, 'debug' => LOG_DEBUG]

$_levels

Handled log levels


    protected
    static    array<string|int, string>
    $_levels
     = ['emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug']

$_registry

LogEngineRegistry class


    protected
    static    LogEngineRegistry
    $_registry

alert()

Convenience method to log alert messages


    public
            static        alert(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

configured()

Returns an array containing the named configurations


    public
            static        configured() : array<string|int, string>

Return values

array<string|int, string> —

Array of configurations.

critical()

Convenience method to log critical messages


    public
            static        critical(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

debug()

Convenience method to log debug messages


    public
            static        debug(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

drop()

Drops a constructed adapter.


    public
            static        drop(string $config) : bool

If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.

If the implementing objects supports a $_registry object the named configuration will also be unloaded from the registry.

Parameters

$config : string: An existing configuration you wish to remove.

Return values

bool —

Success of the removal, returns false when the config does not exist.

emergency()

Convenience method to log emergency messages


    public
            static        emergency(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

engine()

Get a logging engine.


    public
            static        engine(string $name) : LoggerInterface|null

Parameters

$name : string: Key name of a configured adapter to get.

Return values

LoggerInterface|null —

Instance of LoggerInterface or false if not found

error()

Convenience method to log error messages


    public
            static        error(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

getConfig()

Reads existing configuration.


    public
            static        getConfig(string $key) : mixed|null

Parameters

$key : string: The name of the configuration.

Return values

mixed|null —

Configuration data at the named key or null if the key does not exist.

getConfigOrFail()

Reads existing configuration for a specific key.


    public
            static        getConfigOrFail(string $key) : mixed

The config value for this key must exist, it can never be null.

Parameters

$key : string: The name of the configuration.

Return values

mixed —

Configuration data at the named key.

getDsnClassMap()

Returns the DSN class map for this class.


    public
            static        getDsnClassMap() : array<string, string>

Return values

array<string, string>

info()

Convenience method to log info messages


    public
            static        info(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically indexed array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

levels()

Gets log levels


    public
            static        levels() : array<string|int, string>

Call this method to obtain current level configuration.

Return values

array<string|int, string> —

Active log levels

notice()

Convenience method to log notice messages


    public
            static        notice(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

parseDsn()

Parses a DSN into a valid connection configuration


    public
            static        parseDsn(string $dsn) : array<string, mixed>

This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:

$dsn = 'mysql://user:pass@localhost/database?';
$config = ConnectionManager::parseDsn($dsn);

$dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS';
$config = Log::parseDsn($dsn);

$dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null';
$config = Email::parseDsn($dsn);

$dsn = 'file:///?className=\My\Cache\Engine\FileEngine';
$config = Cache::parseDsn($dsn);

$dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/';
$config = Cache::parseDsn($dsn);

For all classes, the value of scheme is set as the value of both the className unless they have been otherwise specified.

Note that querystring arguments are also parsed and set as values in the returned configuration.

Parameters

$dsn : string: The DSN string to convert to a configuration array

Return values

array<string, mixed> —

The configuration array to be stored after parsing the DSN

reset()

Reset all the connected loggers. This is useful to do when changing the logging configuration or during testing when you want to reset the internal state of the Log class.


    public
            static        reset() : void

Resets the configured logging adapters, as well as any custom logging levels. This will also clear the configuration data.

setConfig()

This method can be used to define logging adapters for an application or read existing configuration.


    public
            static        setConfig(array<string, mixed>|string $key[, array<string, mixed>|Closure|null $config = null ]) : void

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Loggers will not be constructed until the first log message is written.

Usage

Setting a cache engine up.

Log::setConfig('default', $settings);

Injecting a constructed adapter in:

Log::setConfig('default', $instance);

Using a factory function to get an adapter:

Log::setConfig('default', function () { return new FileLog(); });

Configure multiple adapters at once:

Log::setConfig($arrayOfConfig);

Parameters

$key : array<string, mixed>|string: The name of the logger config, or an array of multiple configs.
$config : array<string, mixed>|Closure|null = null: An array of name => config data for adapter.

setDsnClassMap()

Updates the DSN class map for this class.


    public
            static        setDsnClassMap(array<string, string> $map) : void

Parameters

$map : array<string, string>: Additions/edits to the class map to apply.

warning()

Convenience method to log warning messages


    public
            static        warning(string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Parameters

$message : string: log message
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

write()

Writes the given message and type to all the configured log adapters.


    public
            static        write(string|int $level, string $message[, array<string|int, mixed>|string $context = [] ]) : bool

Configured adapters are passed both the $level and $message variables. $level is one of the following strings/values.

Levels:

LOG_EMERG => 'emergency',
LOG_ALERT => 'alert',
LOG_CRIT => 'critical',
LOG_ERR => 'error',
LOG_WARNING => 'warning',
LOG_NOTICE => 'notice',
LOG_INFO => 'info',
LOG_DEBUG => 'debug',

Basic usage

Write a 'warning' message to the logs:

Log::write('warning', 'Stuff is broken here');

Using scopes

When writing a log message you can define one or many scopes for the message. This allows you to handle messages differently based on application section/feature.

Log::write('warning', 'Payment failed', ['scope' => 'payment']);

When configuring loggers you can configure the scopes a particular logger will handle. When using scopes, you must ensure that the level of the message, and the scope of the message intersect with the defined levels & scopes for a logger.

Unhandled log messages

If no configured logger can handle a log message (because of level or scope restrictions) then the logged message will be ignored and silently dropped. You can check if this has happened by inspecting the return of write(). If false the message was not handled.

Parameters

$level : string|int: The severity level of the message being written. The value must be an integer or string matching a known level.
$message : string: Message content to log
$context : array<string|int, mixed>|string = []: Additional data to be used for logging the message. The special scope key can be passed to be used for further filtering of the log engines to be used. If a string or a numerically index array is passed, it will be treated as the scope key. See for more information on logging scopes.

Return values

bool —

Success

_init()

Initializes registry and configurations


    protected
            static        _init() : void

_loadConfig()

Load the defined configuration and create all the defined logging adapters.


    protected
            static        _loadConfig() : void

Log in package Application uses StaticConfigTrait

Configuring Log adapters

Logging levels

Logging scopes

Writing to the log

Logging Levels

Logging scopes

Table of Contents

Properties

Methods

Properties

$_config

$_dirtyConfig

$_dsnClassMap

Tags

$_levelMap

$_levels

$_registry

Methods

alert()

Parameters

Return values

configured()

Return values

critical()

Parameters

Return values

debug()

Parameters

Return values

drop()

Parameters

Return values

emergency()

Parameters

Return values

engine()

Parameters

Return values

error()

Parameters

Return values

getConfig()

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getDsnClassMap()

Tags

Return values

info()

Parameters

Return values

levels()

Return values

notice()

Parameters

Return values

parseDsn()

Parameters

Tags

Return values

reset()

setConfig()

Usage

Parameters

Tags

setDsnClassMap()

Parameters

Tags

warning()

Parameters

Return values

write()

Levels:

Basic usage

Using scopes

Unhandled log messages

Log
in package

Application

uses StaticConfigTrait