pls/log

PLS logger specification

Pls/Log

, _(*1)

This package describes a common interface for logging libraries. Its goal is to allow libraries to receive an object implementing Pls\Log\Logger and write logs to it in a simple and universal way., _(*2)

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119., _(*3)

1. Specification

Implementations MUST implement the specified functionality entirely and MAY provide more functionality than specified., _(*4)

The Pls\Log\LoggerInterface exposes a method, log, to log messages. log accepts three arguments: $level, $message and $context (optional)., _(*5)

1.1 $level

This is an int value, corresponding to one of the eight RFC 5424 severity levels., _(*6)

An interface, LogLevel, provides constants with semantic labels mapped to the int severity levels. Users are RECOMMENDED to pass these constants as $level values., _(*7)

Passing a $level value that is not defined by this specification, i.e. that is not >= 0 and <= 7, MUST throw an instance of Pls\Log\InvalidSeverity., _(*8)

1.2 $message

This is a user-defined string value to log., _(*9)

The message MAY contain placeholders which implementors MAY replace with values from the context array., _(*10)

Placeholder names MUST correspond to keys in the context array., _(*11)

Placeholder names MUST be delimited with a single opening brace { and a single closing brace }. There MUST NOT be any whitespace between the delimiters and the placeholder name., _(*12)

Placeholder names MUST be composed only of the characters A-Z, a-z, 0-9, underscore _, and period .., _(*13)

Implementors MAY use placeholders to implement various escaping strategies and translate logs for display. Users SHOULD NOT pre-escape placeholder values since they can not know in which context the data will be displayed., _(*14)

Passing a $message value that contains a malformed placeholder name MUST throw an instance of Pls\Log\InvalidMessage., _(*15)

1.3 $context

This is an optional user-defined array; the default value is an empty array, []. This is meant to hold any extraneous information that does not fit well in a string. The array can contain anything. A given value in the context MUST NOT throw an exception nor raise any PHP error, warning or notice., _(*16)

Array keys and values MAY be of any type PHP permits and MAY be of different types within a $context array, except that an array key corresponding to a placeholder name must be a string, identical to the placeholder name in $message., _(*17)

An array value MUST be provided for each placeholder name in $message. Passing a $context array that does not contain a key corresponding to a placeholder name which is present in the passed $message MUST throw an instance of Pls\Log\InvalidContext., _(*18)

If an object implementing \Throwable is passed in the context data, it MUST be in the 'thrown' key. Logging exceptions is a common pattern and this allows implementors to extract a stack trace from the exception when the log backend supports it. Implementors MUST still verify that the 'thrown' key is actually a \Thowable before using it as such, as it MAY contain anything., _(*19)

1.4 Exceptions

All exceptions thrown by implementations MUST implement Pls\Log\LoggerException., _(*20)

2. Package

The interfaces are provided as part of the pls/log package., _(*21)

Packages providing a pls/log implementation SHOULD declare that they provide pls/log-implementation 1.0.0., _(*22)

Projects requiring an implementation SHOULD require pls/log-implementation ^1.0.0., _(*23)

3. Installation

To install with composer:, _(*24)

composer require pls/log

Requires PHP >= 7.3., _(*25)

4. License

This package is released under the MIT license., _(*26)