pls / log
PLS logger specification
Requires
- php: ^7.3
This package is not auto-updated.
Last update: 2024-10-27 05:04:29 UTC
README
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.
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.
1. Specification
Implementations MUST implement the specified functionality entirely and MAY provide more functionality than specified.
The Pls\Log\LoggerInterface
exposes a method, log
, to log messages. log
accepts three arguments: $level
, $message
and $context
(optional).
1.1 $level
This is an int
value, corresponding to one of the eight RFC 5424 severity levels.
An interface, LogLevel
, provides constants with semantic labels mapped to the int
severity levels. Users are RECOMMENDED to pass these constants as $level
values.
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
.
1.2 $message
This is a user-defined string
value to log.
The message MAY contain placeholders which implementors MAY replace with values from the context array.
Placeholder names MUST correspond to keys in the context array.
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.
Placeholder names MUST be composed only of the characters A-Z
, a-z
, 0-9
, underscore _
, and period .
.
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.
Passing a $message
value that contains a malformed placeholder name MUST throw an instance of Pls\Log\InvalidMessage
.
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.
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
.
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
.
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.
1.4 Exceptions
All exceptions thrown by implementations MUST implement Pls\Log\LoggerException
.
2. Package
The interfaces are provided as part of the pls/log package.
Packages providing a pls/log implementation SHOULD declare that they provide pls/log-implementation
1.0.0
.
Projects requiring an implementation SHOULD require pls/log-implementation
^1.0.0
.
3. Installation
To install with composer:
composer require pls/log
Requires PHP >= 7.3.
4. License
This package is released under the MIT license.