PHP PSR-3 log interface specification-PHP Tutorial-php.cn

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())

{

// Construct a curly bracket enclosed Replacement array of key names

$replace = 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
3. namespace PsrLog;
5. /**
6. * Logging instance
7. *
8. * Log information variable - message, **must** be a string or an object that implements the __toString() method.
9. *
10. * The log information variable **can** contain a placeholder in the format "{foo}" (representing foo),
11. * which will be replaced by the key value "foo" in the context array.
12. *
13. * The context array can carry any data. The only restriction is that when it carries an exception object, its key name must be "exception".
14. *
15. * For details, please refer to: https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md
16. */
17. interface LoggerInterface
18. {
19. /**
20. * The system is unavailable
21. *
22. * @param string $message
23. * @param array $context
24. * @return null
25. */
26. public function emergency($message, array $context = array());
28. /**
29. * **Must** take action immediately
30. *
31. * 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.
32. *
33. * @param string $message
34. * @param array $context
35. * @return null
36. */
37. public function alert($message, array $context = array());
39. /**
40. * Emergency
41. *
42. * For example: program components are unavailable or unexpected exceptions occur.
43. *
44. * @param string $message
45. * @param array $context
46. * @return null
47. */
48. public function critical($message, array $context = array());
50. /**
51. * Errors that occur during runtime do not require immediate action, but must be recorded for detection.
52. *
53. * @param string $message
54. * @param array $context
55. * @return null
56. */
57. public function error($message, array $context = array());
59. /**
60. * A non-error exception occurred.
61. *
62. * For example: using a deprecated API, using an API incorrectly or causing unexpected and unnecessary errors.
63. *
64. * @param string $message
65. * @param array $context
66. * @return null
67. */
68. public function warning($message, array $context = array());
70. /**
71. *Generally important events.
72. *
73. * @param string $message
74. * @param array $context
75. * @return null
76. */
77. public function notice($message, array $context = array());
79. /**
80. * Important events
81. *
82. * For example: user login and SQL records.
83. *
84. * @param string $message
85. * @param array $context
86. * @return null
87. */
88. public function info($message, array $context = array());
90. /**
91. * debug details
92. *
93. * @param string $message
94. * @param array $context
95. * @return null
96. */
97. public function debug($message, array $context = array());
99. /**
100. * Logging at any level
101. *
102. * @param mixed $level
103. * @param string $message
104. * @param array $context
105. * @return null
106. */
107. public function log($level, $message, array $context = array());
108. }
复制代码
PsrLogLoggerAwareInterface
3. namespace PsrLog;
5. /**
6. * logger-aware definition instance
7. */
8. interface LoggerAwareInterface
9. {
10. /**
11. * Set up a logging instance
12. *
13. * @param LoggerInterface $logger
14. * @return null
15. */
16. public function setLogger(LoggerInterface $logger);
17. }
复制代码
PsrLogLogLevel
3. namespace PsrLog;
5. /**
6. * Log level constant definition
7. */
8. class LogLevel
9. {
10. const EMERGENCY = 'emergency';
11. const ALERT = 'alert';
12. const CRITICAL = 'critical';
13. const ERROR = 'error';
14. const WARNING = 'warning';
15. const NOTICE = 'notice';
16. const INFO = 'info';
17. const DEBUG = 'debug';
18. }
复制代码
转自Github(PizzaLiu)

PHP, PSR