Class Log

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.

Namespace: Cake\Log

Property Summary

$_config protected static

array

Configuration sets.
$_dirtyConfig protected static

bool

Internal flag for tracking whether or not configuration has been changed.
$_dsnClassMap protected static

string[]

An array mapping url schemes to fully qualified Log engine class names
$_levelMap protected static

array

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

string[]

Handled log levels
$_registry protected static

Cake\Log\LogEngineRegistry|null

LogEngineRegistry class

Method Summary

_init() protected static

Initializes registry and configurations
_loadConfig() protected static

Load the defined configuration and create all the defined logging adapters.
alert() public static

Convenience method to log alert messages
config() public static deprecated

This method can be used to define configuration adapters for an application or read existing configuration.
configured() public static

Returns an array containing the named configurations
critical() public static

Convenience method to log critical messages
debug() public static

Convenience method to log debug messages
drop() public static

Drops a constructed adapter.
dsnClassMap() public static deprecated

Returns or updates the DSN class map for this class.
emergency() public static

Convenience method to log emergency messages
engine() public static

Get a logging engine.
error() public static

Convenience method to log error messages
getConfig() public static

Reads existing configuration.
getDsnClassMap() public static

Returns the DSN class map for this class.
info() public static

Convenience method to log info messages
levels() public static

Gets log levels
notice() public static

Convenience method to log notice messages
parseDsn() public static

Parses a DSN into a valid connection configuration
reset() public static

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() public static

This method can be used to define logging adapters for an application or read existing configuration.
setDsnClassMap() public static

Updates the DSN class map for this class.
warning() public static

Convenience method to log warning messages
write() public static

Writes the given message and type to all of the configured log adapters. Configured adapters are passed both the $level and $message variables. $level is one of the following strings/values.

Method Detail

_init() ¶ protected static

_init(): void

Initializes registry and configurations

Returns

void

_loadConfig() ¶ protected static

_loadConfig(): void

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

Returns

void

alert() ¶ public static

alert(string $message, string|array $context = []): bool

Convenience method to log alert messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

config() ¶ public static

config(string|array $key, array|null $config = null): array|null

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

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

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Reading config data back:

Cache::config('default');

Setting a cache engine up.

Cache::config('default', $settings);

Injecting a constructed adapter in:

Cache::config('default', $instance);

Configure multiple adapters at once:

Cache::config($arrayOfConfig);

Parameters

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

Returns

array|null

Throws

BadMethodCallException
When trying to modify an existing config.

configured() ¶ public static

configured(): string[]

Returns an array containing the named configurations

Returns

string[]

critical() ¶ public static

critical(string $message, string|array $context = []): bool

Convenience method to log critical messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

debug() ¶ public static

debug(string $message, string|array $context = []): bool

Convenience method to log debug messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

drop() ¶ public static

drop(string $config): bool

Drops a constructed adapter.

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

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

Returns

bool

dsnClassMap() ¶ public static

dsnClassMap(string[]|null $map = null): string[]

Returns or updates the DSN class map for this class.

Parameters

string[]|null $map optional: Additions/edits to the class map to apply.

Returns

string[]

emergency() ¶ public static

emergency(string $message, string|array $context = []): bool

Convenience method to log emergency messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

engine() ¶ public static

engine(string $name): Cake\Log\Engine\BaseLog|false

Get a logging engine.

Parameters

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

Returns

Cake\Log\Engine\BaseLog|false

error() ¶ public static

error(string $message, string|array $context = []): bool

Convenience method to log error messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

getConfig() ¶ public static

getConfig(string $key): mixed

Reads existing configuration.

Parameters

string $key: The name of the configuration.

Returns

mixed

getDsnClassMap() ¶ public static

getDsnClassMap(): string[]

Returns the DSN class map for this class.

Returns

string[]

info() ¶ public static

info(string $message, string|array $context = []): bool

Convenience method to log info messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

levels() ¶ public static

levels(): string[]

Gets log levels

Call this method to obtain current level configuration.

Returns

string[]

notice() ¶ public static

notice(string $message, string|array $context = []): bool

Convenience method to log notice messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

parseDsn() ¶ public static

parseDsn(string $dsn): array

Parses a DSN into a valid connection configuration

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

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

Returns

array

Throws

InvalidArgumentException
If not passed a string, or passed an invalid string

reset() ¶ public static

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.

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

Returns

void

setConfig() ¶ public static

setConfig(string|array $key, array|object|null $config = null): void

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

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

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

Returns

void

Throws

BadMethodCallException
When trying to modify an existing config.

setDsnClassMap() ¶ public static

setDsnClassMap(string[] $map): void

Updates the DSN class map for this class.

Parameters

string[] $map: Additions/edits to the class map to apply.

Returns

void

warning() ¶ public static

warning(string $message, string|array $context = []): bool

Convenience method to log warning messages

Parameters

string $message: log message
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

write() ¶ public static

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

Writes the given message and type to all of the configured log adapters. 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

int|string $level: The severity level of the message being written. The value must be an integer or string matching a known level.
mixed $message: Message content to log
string|array $context optional: 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 Cake\Log\Log::setConfig() for more information on logging scopes.

Returns

bool

Throws

InvalidArgumentException
If invalid level is passed.

Property Detail

`$_config` ¶ protected static

Configuration sets.

Type

array

`$_dirtyConfig` ¶ protected static

Internal flag for tracking whether or not configuration has been changed.

Type

bool

`$_dsnClassMap` ¶ protected static

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

Type

string[]

`$_levelMap` ¶ protected static

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

Type

array

`$_levels` ¶ protected static

Handled log levels

Type

string[]

`$_registry` ¶ protected static

LogEngineRegistry class

Type

Cake\Log\LogEngineRegistry|null

Namespaces

Class Log

Configuring Log adapters

Logging levels

Logging scopes

Writing to the log

Logging Levels

Logging scopes

Property Summary

Method Summary

_init() protected static

_loadConfig() protected static

alert() public static

config() public static deprecated

configured() public static

critical() public static

debug() public static

drop() public static

dsnClassMap() public static deprecated

emergency() public static

engine() public static

error() public static

getConfig() public static

getDsnClassMap() public static

info() public static

levels() public static

notice() public static

parseDsn() public static

reset() public static

setConfig() public static

setDsnClassMap() public static

warning() public static

write() public static

Method Detail

_init() ¶ protected static

Returns

_loadConfig() ¶ protected static

Returns

alert() ¶ public static

Parameters

Returns

config() ¶ public static

Usage

Parameters

Returns

Throws

configured() ¶ public static

Returns

critical() ¶ public static

Parameters

Returns

debug() ¶ public static

Parameters

Returns

drop() ¶ public static

Parameters

Returns

dsnClassMap() ¶ public static

Parameters

Returns

emergency() ¶ public static

Parameters

Returns

engine() ¶ public static

Parameters

Returns

error() ¶ public static

Parameters

Returns

getConfig() ¶ public static

Parameters

Returns

getDsnClassMap() ¶ public static

Returns

info() ¶ public static

Parameters

Returns

levels() ¶ public static

Returns

notice() ¶ public static

`$_config` ¶ protected static

`$_dirtyConfig` ¶ protected static

`$_dsnClassMap` ¶ protected static

`$_levelMap` ¶ protected static

`$_levels` ¶ protected static

`$_registry` ¶ protected static