Documentation

Logger
in package
implements LoggerInterface, ResettableInterface

Monolog log channel

It contains a stack of Handlers and a stack of Processors, and uses them to store records that are added to it.

Tags
author

Jordi Boggiano j.boggiano@seld.be

phpstan-type

Level Logger::DEBUG|Logger::INFO|Logger::NOTICE|Logger::WARNING|Logger::ERROR|Logger::CRITICAL|Logger::ALERT|Logger::EMERGENCY

phpstan-type

LevelName 'DEBUG'|'INFO'|'NOTICE'|'WARNING'|'ERROR'|'CRITICAL'|'ALERT'|'EMERGENCY'

phpstan-type

Record array{message: string, context: mixed[], level: Level, level_name: LevelName, channel: string, datetime: \DateTimeImmutable, extra: mixed[]}

Interfaces, Classes and Traits

LoggerInterface
Describes a logger instance.
ResettableInterface
Handler or Processor implementing this interface will be reset when Logger::reset() is called.

Table of Contents

ALERT  = 550
Action must be taken immediately
API  = 2
Monolog API version
CRITICAL  = 500
Critical conditions
DEBUG  = 100
Detailed debug information
EMERGENCY  = 600
Urgent alert.
ERROR  = 400
Runtime errors
INFO  = 200
Interesting events
NOTICE  = 250
Uncommon events
WARNING  = 300
Exceptional occurrences that are not errors
RFC_5424_LEVELS  = [7 => self::DEBUG, 6 => self::INFO, 5 => self::NOTICE, 4 => self::WARNING, 3 => self::ERROR, 2 => self::CRITICAL, 1 => self::ALERT, 0 => self::EMERGENCY]
Mapping between levels numbers defined in RFC 5424 and Monolog ones
$exceptionHandler  : callable|null
$handlers  : array<string|int, HandlerInterface>
The handler stack
$levels  : array<int, string>
This is a static variable and not a constant to serve as an extension point for custom levels
$microsecondTimestamps  : bool
$name  : string
$processors  : array<string|int, callable>
Processors that will process all log records
$timezone  : DateTimeZone
$detectCycles  : bool
$fiberLogDepth  : WeakMap<Fiber, int>|null
$logDepth  : int
__construct()  : mixed
__serialize()  : array<string, mixed>
__unserialize()  : void
addRecord()  : bool
Adds a log record.
alert()  : void
Adds a log record at the ALERT level.
close()  : void
Ends a log cycle and frees all resources used by handlers.
critical()  : void
Adds a log record at the CRITICAL level.
debug()  : void
Adds a log record at the DEBUG level.
emergency()  : void
Adds a log record at the EMERGENCY level.
error()  : void
Adds a log record at the ERROR level.
getExceptionHandler()  : callable|null
getHandlers()  : array<string|int, HandlerInterface>
getLevelName()  : string
Gets the name of the logging level.
getLevels()  : array<string, int>
Gets all supported logging levels.
getName()  : string
getProcessors()  : array<string|int, callable>
getTimezone()  : DateTimeZone
Returns the timezone to be used for the timestamp of log records.
info()  : void
Adds a log record at the INFO level.
isHandling()  : bool
Checks whether the Logger has a handler that listens on the given level
log()  : void
Adds a log record at an arbitrary level.
notice()  : void
Adds a log record at the NOTICE level.
popHandler()  : HandlerInterface
Pops a handler from the stack
popProcessor()  : callable
Removes the processor on top of the stack and returns it.
pushHandler()  : self
Pushes a handler on to the stack.
pushProcessor()  : self
Adds a processor on to the stack.
reset()  : void
Ends a log cycle and resets all handlers and processors to their initial state.
setExceptionHandler()  : self
Set a custom exception handler that will be called if adding a new record fails
setHandlers()  : self
Set handlers, replacing all existing ones.
setTimezone()  : self
Sets the timezone to be used for the timestamp of log records.
toMonologLevel()  : int
Converts PSR-3 levels to Monolog ones if necessary
useLoggingLoopDetection()  : self
useMicrosecondTimestamps()  : self
Control the use of microsecond resolution timestamps in the 'datetime' member of new records.
warning()  : void
Adds a log record at the WARNING level.
withName()  : self
Return a new cloned instance with the name changed
handleException()  : void
Delegates exception management to the custom exception handler, or throws the exception if no custom handler is set.

Constants

ALERT

Action must be taken immediately

public mixed ALERT = 550

Example: Entire website down, database unavailable, etc. This should trigger the SMS alerts and wake you up.

API

Monolog API version

public int API = 2

This is only bumped when API breaks are done and should follow the major version of the library

CRITICAL

Critical conditions

public mixed CRITICAL = 500

Example: Application component unavailable, unexpected exception.

DEBUG

Detailed debug information

public mixed DEBUG = 100

EMERGENCY

Urgent alert.

public mixed EMERGENCY = 600

ERROR

Runtime errors

public mixed ERROR = 400

INFO

Interesting events

public mixed INFO = 200

Examples: User logs in, SQL logs.

NOTICE

Uncommon events

public mixed NOTICE = 250

WARNING

Exceptional occurrences that are not errors

public mixed WARNING = 300

Examples: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.

RFC_5424_LEVELS

Mapping between levels numbers defined in RFC 5424 and Monolog ones

private mixed RFC_5424_LEVELS = [7 => self::DEBUG, 6 => self::INFO, 5 => self::NOTICE, 4 => self::WARNING, 3 => self::ERROR, 2 => self::CRITICAL, 1 => self::ALERT, 0 => self::EMERGENCY]
Tags
phpstan-var

array<int, Level> $rfc_5424_levels

Properties

$exceptionHandler

protected callable|null $exceptionHandler

$levels

This is a static variable and not a constant to serve as an extension point for custom levels

protected static array<int, string> $levels = [self::DEBUG => 'DEBUG', self::INFO => 'INFO', self::NOTICE => 'NOTICE', self::WARNING => 'WARNING', self::ERROR => 'ERROR', self::CRITICAL => 'CRITICAL', self::ALERT => 'ALERT', self::EMERGENCY => 'EMERGENCY']

Logging levels with the levels as key

Tags
phpstan-var

array<Level, LevelName> $levels Logging levels with the levels as key

$microsecondTimestamps

protected bool $microsecondTimestamps = true

$processors

Processors that will process all log records

protected array<string|int, callable> $processors

To process records of a single handler instead, add the processor on that specific handler

$timezone

protected DateTimeZone $timezone

$detectCycles

private bool $detectCycles = true

Whether to detect infinite logging loops

$fiberLogDepth

private WeakMap<Fiber, int>|null $fiberLogDepth

Keeps track of depth inside fibers to prevent infinite logging loops

$logDepth

private int $logDepth = 0

Keeps track of depth to prevent infinite logging loops

Methods

__construct()

public __construct(string $name[, array<string|int, HandlerInterface> $handlers = [] ][, array<string|int, callable> $processors = [] ][, DateTimeZone|null $timezone = null ]) : mixed
Parameters
$name : string

The logging channel, a simple descriptive name that is attached to all log records

$handlers : array<string|int, HandlerInterface> = []

Optional stack of handlers, the first one in the array is called first, etc.

$processors : array<string|int, callable> = []

Optional array of processors

$timezone : DateTimeZone|null = null

Optional timezone, if not provided date_default_timezone_get() will be used

Tags
psalm-param

array<callable(array): array> $processors

Return values
mixed —

__serialize()

public __serialize() : array<string, mixed>
Return values
array<string, mixed> —

__unserialize()

public __unserialize(array<string, mixed> $data) : void
Parameters
$data : array<string, mixed>
Return values
void —

addRecord()

Adds a log record.

public addRecord(int $level, string $message[, array<string|int, mixed> $context = [] ][, DateTimeImmutable $datetime = null ]) : bool
Parameters
$level : int

The logging level (a Monolog or RFC 5424 level)

$message : string

The log message

$context : array<string|int, mixed> = []

The log context

$datetime : DateTimeImmutable = null

Optional log date to log into the past or future

Tags
phpstan-param

Level $level

Return values
bool —

Whether the record has been processed

alert()

Adds a log record at the ALERT level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

close()

Ends a log cycle and frees all resources used by handlers.

public close() : void

Closing a Handler means flushing all buffers and freeing any open resources/handles. Handlers that have been closed should be able to accept log records again and re-open themselves on demand, but this may not always be possible depending on implementation.

This is useful at the end of a request and will be called automatically on every handler when they get destructed.

Return values
void —

critical()

Adds a log record at the CRITICAL level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

debug()

Adds a log record at the DEBUG level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

emergency()

Adds a log record at the EMERGENCY level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

error()

Adds a log record at the ERROR level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

getExceptionHandler()

public getExceptionHandler() : callable|null
Return values
callable|null —

getLevelName()

Gets the name of the logging level.

public static getLevelName(int $level) : string
Parameters
$level : int
Tags
throws
InvalidArgumentException

If level is not defined

phpstan-param

Level $level

phpstan-return

LevelName

Return values
string —

getLevels()

Gets all supported logging levels.

public static getLevels() : array<string, int>
Tags
phpstan-return

array<LevelName, Level>

Return values
array<string, int> —

Assoc array with human-readable level names => level codes.

getName()

public getName() : string
Return values
string —

getProcessors()

public getProcessors() : array<string|int, callable>
Return values
array<string|int, callable> —

getTimezone()

Returns the timezone to be used for the timestamp of log records.

public getTimezone() : DateTimeZone
Return values
DateTimeZone —

info()

Adds a log record at the INFO level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

isHandling()

Checks whether the Logger has a handler that listens on the given level

public isHandling(int $level) : bool
Parameters
$level : int
Tags
phpstan-param

Level $level

Return values
bool —

log()

Adds a log record at an arbitrary level.

public log(mixed $level, string|Stringable $message[, array<string|int, mixed> $context = [] ]) : void

This method allows for compatibility with common interfaces.

Parameters
$level : mixed

The log level (a Monolog, PSR-3 or RFC 5424 level)

$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Tags
phpstan-param

Level|LevelName|LogLevel::* $level

Return values
void —

notice()

Adds a log record at the NOTICE level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

popProcessor()

Removes the processor on top of the stack and returns it.

public popProcessor() : callable
Tags
throws
LogicException

If empty processor stack

Return values
callable —

pushProcessor()

Adds a processor on to the stack.

public pushProcessor(callable $callback) : self
Parameters
$callback : callable
Return values
self —

reset()

Ends a log cycle and resets all handlers and processors to their initial state.

public reset() : void

Resetting a Handler or a Processor means flushing/cleaning all buffers, resetting internal state, and getting it back to a state in which it can receive log records again.

This is useful in case you want to avoid logs leaking between two requests or jobs when you have a long running process like a worker or an application server serving multiple requests in one process.

Return values
void —

setExceptionHandler()

Set a custom exception handler that will be called if adding a new record fails

public setExceptionHandler(callable|null $callback) : self

The callable will receive an exception object and the record that failed to be logged

Parameters
$callback : callable|null
Return values
self —

setHandlers()

Set handlers, replacing all existing ones.

public setHandlers(array<string|int, HandlerInterface> $handlers) : self

If a map is passed, keys will be ignored.

Parameters
$handlers : array<string|int, HandlerInterface>
Return values
self —

setTimezone()

Sets the timezone to be used for the timestamp of log records.

public setTimezone(DateTimeZone $tz) : self
Parameters
$tz : DateTimeZone
Return values
self —

toMonologLevel()

Converts PSR-3 levels to Monolog ones if necessary

public static toMonologLevel(string|int $level) : int
Parameters
$level : string|int

Level number (monolog) or name (PSR-3)

Tags
throws
InvalidArgumentException

If level is not defined

phpstan-param

Level|LevelName|LogLevel::* $level

phpstan-return

Level

Return values
int —

useLoggingLoopDetection()

public useLoggingLoopDetection(bool $detectCycles) : self
Parameters
$detectCycles : bool
Return values
self —

useMicrosecondTimestamps()

Control the use of microsecond resolution timestamps in the 'datetime' member of new records.

public useMicrosecondTimestamps(bool $micro) : self

As of PHP7.1 microseconds are always included by the engine, so there is no performance penalty and Monolog 2 enabled microseconds by default. This function lets you disable them though in case you want to suppress microseconds from the output.

Parameters
$micro : bool

True to use microtime() to create timestamps

Return values
self —

warning()

Adds a log record at the WARNING level.

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

This method allows for compatibility with common interfaces.

Parameters
$message : string|Stringable

The log message

$context : array<string|int, mixed> = []

The log context

Return values
void —

withName()

Return a new cloned instance with the name changed

public withName(string $name) : self
Parameters
$name : string
Return values
self —

handleException()

Delegates exception management to the custom exception handler, or throws the exception if no custom handler is set.

protected handleException(Throwable $e, array<string|int, mixed> $record) : void
Parameters
$e : Throwable
$record : array<string|int, mixed>
Tags
phpstan-param

Record $record

Return values
void —

Search results