PHP PSR-3 log interface specification

Log interface specification

This article formulates the general interface specification of the log library.

The main purpose of this specification is to allow the logging library to record log information in a simple and universal way by receiving a PsrLogLoggerInterface object.
If necessary, the framework and CMS content management system can extend this interface, but they must follow this specification. This can ensure that the log interface can still be connected normally when using third-party class library files.

Keywords "must" ("MUST"), "must not/must not" ("MUST NOT"), "need" ("REQUIRED"),

"will" ("SHALL"), "won't" ("SHALL NOT"), "should" ("SHOULD"), "should not" ("SHOULD NOT"),
"recommended" ("RECOMMENDED"), "can" ("MAY") and "optional" ("OPTIONAL") is described in detail in [RFC 2119][].

The implementer in this article refers to the class library or framework that implements the LoggerInterface interface. In turn, they are the users of LoggerInterface.

Specifications

1.1 Basic specifications

---

The LoggerInterface interface defines eight external methods, which are used to record the eight levels of logs defined in [RFC 5424][]: debug, info, notice, warning, error, critical, alert and emergency.

The ninth method - log, its first parameter is the level of the record. This method can be called using a predefined level constant as a parameter, which must have the same effect as directly calling the above eight methods. If the incoming level constant parameter is not predefined, an exception of type PsrLogInvalidArgumentException must be thrown. Users

should not call this method using unsupported level constants under uncertain circumstances. 1.2 Record information Each of the above methods accepts a string type or an object with __toString() method as the record information parameter, so that the implementer can treat it as a string, otherwise the implementer mustconvert it by themselves into a string.

The record information parameters

can carry placeholders, and the implementer can

replace others with corresponding values ​​​​according to the context.

where the placeholder must be consistent with the key name in the context array.

The placeholder name

must be enclosed by an opening curly bracket { and a closing bracket }. But there must be no spaces between the curly braces and the name.

The name of the placeholder

should only consist of A-Z, a-z, 0-9, underscore _, and English period ., other characters are reserved for future placeholder specifications. Implementers can

generate the final log by applying different escaping and conversion strategies for placeholders.

And the user should not escape the placeholder in advance without knowing the context.

The following is an example of placeholder usage:

/** * Replace placeholders in record information with contextual information

*/

function interpolate($message, array $context = array())

{

 $replace['{' . $key . '}'] = $val;
 }

 //Replace the placeholders in the record information, and finally return the modified record information.
 return strtr($message, $replace);
}

// Contains record information with curly bracket placeholders.
$message = "User {username} created";

// Context array with replacement information, the key name is the placeholder name, and the key value is the replacement value.
$context = array('username' => 'bolivar');

// Output "Username bolivar created"
echo interpolate($message, $context);


Copy code

1.3 Context

Each recording function accepts a context array parameter to load information that cannot be represented by the string type. It  can  load any information, so the implementer  must  ensure that it can correctly handle the information it loads. For the data it loads,  must not  throw exceptions, or generate PHP errors, warnings or reminder messages (error, warning , notice). 
If an Exception object is passed in through the context parameter, must use 'exception' as the key name. Logging exception information is very common, so if it can be implemented at the bottom of the logging class library, it will allow the implementer to get rid of the exception information. Of course, when using it, the implementer must  ensure whether the key value with the key name 'exception' is really an Exception, after all, it  can  load any information. 

1.4 Helper classes and interfaces

The PsrLogAbstractLogger class makes it easy to implement the LoggerInterface interface by simply inheriting it and implementing the log method, and the other eight methods can pass logging information and context information to it. 
Similarly, to use PsrLogLoggerTrait, you only need to implement the log method. However, it is important to note that LoggerInterface needs to be implemented before the traits reusable code block can implement the interface. 
When there is no available logger, the PsrLogNullLogger interface  can  provide users with a backup log "black hole". However, when context construction is very resource-intensive, logging with conditional checks may be a better approach. 
The PsrLogLoggerAwareInterface interface only includes a setLogger(LoggerInterface $logger) method, which the framework can use to automatically connect to any logging instance. 
The reusable code block of the PsrLogLoggerAwareTrait trait can be used in any class, and the equivalent interface can be easily implemented through the $this->logger it provides. 
The PsrLogLogLevel class loads eight logging level constants. 

Bag

The above interfaces, classes and related exception classes, as well as a series of implementation detection files, are included in the psr/log file package. 
PsrLogLoggerInterface



namespace PsrLog;

/**
 * Logging instance
 *
 * Log information variable - message, **must** be a string or an object that implements the __toString() method.
 *
 * The log information variable **can** contain a placeholder in the format "{foo}" (representing foo),
 * which will be replaced by the key value "foo" in the context array.
 *
 * The context array can carry any data. The only restriction is that when it carries an exception object, its key name must be "exception".
 *
 * For details, please refer to: https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md
*/
interface LoggerInterface
{
    /**
 * The system is unavailable
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function emergency($message, array $context = array());

    /**
 * **Must** take action immediately
 *
 * For example: in the event that the entire website is down, the database is unavailable, or other circumstances, an alert text message should be sent to wake you up.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function alert($message, array $context = array());

    /**
 * Emergency
 *
 * For example: program components are unavailable or unexpected exceptions occur.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function critical($message, array $context = array());

    /**
 * Errors that occur during runtime do not require immediate action, but must be recorded for detection.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function error($message, array $context = array());

    /**
 * A non-error exception occurred.
 *
 * For example: using a deprecated API, using an API incorrectly or causing unexpected and unnecessary errors.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function warning($message, array $context = array());

    /**
 *Generally important events.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function notice($message, array $context = array());

    /**
 * Important events
 *
 * For example: user login and SQL records.
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function info($message, array $context = array());

    /**
 * debug details
 *
 * @param string $message
 * @param array $context
 * @return null
*/
    public function debug($message, array $context = array());

    /**
 * Logging at any level
 *
 * @param mixed $level
 * @param string $message
 * @param array $context
 * @return null
*/
    public function log($level, $message, array $context = array());
}
PsrLogLoggerAwareInterface



namespace PsrLog;

/**
 * logger-aware definition instance
*/
interface LoggerAwareInterface
{
    /**
 * Set up a logging instance
 *
 * @param LoggerInterface $logger
 * @return null
*/
    public function setLogger(LoggerInterface $logger);
}
PsrLogLogLevel



namespace PsrLog;

/**
 * Log level constant definition
*/
class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}
转自Github(PizzaLiu)

PHP, PSR