Specification for PHPPSR-3 log interfaces

Specification for PHPPSR-3 log interfaces

Log interface specification This article develops a general interface specification for the log class library. The main purpose of this specification is to allow the Log class library to record the Log information in a simple and common way by receiving a Psr \ Log \ LoggerInterface object. If necessary,YesThis API is extended, but this specification must be followed, This ensures that the log interface can still be normally connected when a third-party class library file is used. Key words: "MUST" ("MUST"), "must not/must not" ("must not"), "need" ("REQUIRED "), "Will" ("SHALL"), "will NOT" ("shall not"), "SHOULD" ("shocould"), "shouldn't" ("shocould NOT "), For detailed descriptions of "recommendations" ("RECOMMENDED"), "Yes" ("MAY"), and "OPTIONAL" ("OPTIONAL"), see [RFC 2119] []. The implementers in this article refer to the class libraries or frameworks that implement the LoggerInterface interface. in turn, they are the users of LoggerInterface. Specifications 1.1 Basic Specifications The LoggerInterface interface defines eight external methods to record the eight levels of logs defined in [RFC 5424: debug, info, notice, warning, error, critical, alert, and emergency. The ninth method, log. The first parameter is the record level. You can use a predefined level constant as a parameter to call this method,RequiredIt has the same effect as directly calling the above eight methods. If the passed level constant parameter is not pre-definedRequiredThrow an exception of the type of SRS \ Log \ InvalidArgumentException. In the case of uncertaintyShouldn'tThis method is called using unsupported level constants. 1.2 Record Information Each of the above methods accepts a string type or an object with the _ toString () method as the record information parameter, so that the implementer can treat it as a string, otherwise the implementerRequiredConvert it into a string. Record Information parametersYesCarry placeholders, implementersYesReplace other values with corresponding values according to the context. PlaceholdersRequiredIt must be consistent with the key name in the context array. Placeholder nameRequiredIncluded by a left curly braces {and a right bracket. But between curly braces and namesCertainly notThere is a space character. Placeholder nameShouldOnly A-Z, a-z, 0-9, underscore _, and English periods. Other characters are reserved as future placeholder specifications. ImplementerYesUse different conversion and conversion policies for placeholders to generate the final log. However, if the user does not know the following,Shouldn'tEscape placeholders in advance. The following is an example of using a placeholder: /** * Replace the placeholder in the record information with context information */ Function interpolate ($ message, array $ context = array ()) { // Construct a replacement array of the key names contained in curly brackets $ Replace = array (); Foreach ($ context as $ key => $ val ){ $ Replace ['{'. $ key. '}'] = $ val; } // Replace the placeholder in the record information and return the modified record information. Return strtr ($ message, $ replace ); } // Record information containing placeholders with curly braces. $ 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 ); 1.3 Context Each record function accepts a context array parameter to load information that cannot be expressed by the string type. ItYesLoad any information, so the implementerRequiredMake sure that you can correctly process the information it loads. for the data it loads,Certainly notThrows an exception or generates PHP errors, warnings, or reminders (error, warning, or notice ). If you need to pass in an Exception object through context parameters,RequiredUse 'exception' as the key name. Recording exception information is common, so if it can be implemented at the underlying layer of the record library, it will allow the real-time users to get rid of the exception information. Of course, when the implementer uses it,RequiredMake sure that the key value 'exception' is an exception.YesLoad any information. 1.4 helper classes and interfaces This makes it easy to implement the LoggerInterface by inheriting it and implementing the Log method, the other eight methods can pass the record information and context information to it. Similarly, you only need to implement the Log method by using the DSRs \ log \ LoggerTrait. However, it should be noted that implement LoggerInterface is also required before traits reusable code blocks cannot implement interfaces. When no Log recorder is available, the SRS \ Log \ NullLogger interfaceYesProvides users with a backup log "black hole ". However, when context building consumes a lot of resources, it may be better to record logs with conditional checks. Only one of the following interfaces is available: SetLogger (LoggerInterface $ logger) method. the framework can use it to automatically connect to any log record instance. You can use this reusable code block in any class by using the $ this-> logger provided by this code block to easily implement the same interface. The Psr \ Log \ LogLevel class contains eight record level constants. Package The above interfaces, classes and related exception classes, as well as a series of implementation detection files, are all included in the SRS/log file package. Psr \ Log \ LoggerInterface Namespace Psr \ Log; /** * Logging instance * * The log information variable -- message, ** must ** be a string or an object that implements the _ toString () method. * * The log information variable ** can ** contain placeholders in the format of "{foo}" (representing foo, * It will be replaced by the key value named "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, see: 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 ()); /** * ** Required ** take immediate action * * For example, if the entire website crashes, the database is unavailable, or in other cases, ** you should ** send an alert text message 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 ()); /** * If an error occurs during running, you do not need to take immediate action, but you must record it for detection. * * @ Param string $ message * @ Param array $ context * @ Return null */ Public function error ($ message, array $ context = array ()); /** * An error is returned. * * For example, an abandoned API is used, an API is incorrectly used, or an unexpected unnecessary error occurs. * * @ Param string $ message * @ Param array $ context * @ Return null */ Public function warning ($ message, array $ context = array ()); /** * General important events. * * @ Param string $ message * @ Param array $ context * @ Return null */ Public function notice ($ message, array $ context = array ()); /** * Important events * * For example, user logon and SQL record. * * @ 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 ()); /** * Log records of any level * * @ Param mixed $ level * @ Param string $ message * @ Param array $ context * @ Return null */ Public function log ($ level, $ message, array $ context = array ()); } Psr \ Log \ LoggerAwareInterface Namespace Psr \ Log; /** * Logger-aware defines an instance */ Interface LoggerAwareInterface { /** * Set a logging instance * * @ Param LoggerInterface $ logger * @ Return null */ Public function setLogger (LoggerInterface $ logger ); } Psr \ Log \ LogLevel Namespace Psr \ Log; /** * Log level constant definition */ Class LogLevel { Const EMERGENCY = 'ergency '; Const ALERT = 'alert '; Const CRITICAL = 'critical '; Const ERROR = 'error '; Const WARNING = 'warning '; Const NOTICE = 'notice '; Const INFO = 'info '; Const DEBUG = 'debug '; }