PSR-3-logger-interface

Bài đăng này đã không được cập nhật trong 6 năm

Giới thiệu .

Hôm trước ngồi bắt đầu gõ PHP, nhưng mà đọc code covetion, có khi còn nhầm nhọt , vì quên chưa thuộc. Thế là thôi, quyết định ngồi đọc code convention thì kiếm được PSR0 to PSR4.
Tham khảo bài viết về code convention của một bạn trên viblo, thấy PSR3 chưa được đề cập đến, nên kiếm tài liệu ngồi dịch, coi như bổ sung.

Logger Interface

Tài liệu này mô tả những interface phổ biến của logging libraries
Mục tiêu chính là việc sử dụng các thư viện so cho việc nhận các Psr\Log\LoggerInterface object sao cho việc ghi log một cách đơn giản và thông thường nhất.

Các Frameworks và các CMSs có thể custom từ các kế thừa các interface có sẵn cho mục đích của họ, tuy nhiên, nó nên được so sánh với tài liệu này. Điều này đảm bảo rằng thư viện bên thứ 3 của ứng dụng sử dụng chúng để viết log một cách tập trung.
Các từ khóa là MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMEND, MAY, OPTIONAL được sử dụng trong tài liệu này có thể giải thích rõ ràng hơn ở RFC 2119
Từ khóa implementor trong tài liệu này được hiểu là ai đó đang cài đặt LoggerInterface* trong các thư viện liên quan đến log, hoặc framework. Người dùng sử dụng logger là *user

Specification

Basic

LoggerInterface đưa ra 8 phương thức để viết logs theo 8 level của RFC 5424, bao gồm debug, info, notice, warning, error, critical, alert, emergency
Phương thức thứ 9 là log, nó đồng ý việc coi log là một level thấp nhất, gọi là mức cơ bản, và là them số đầu vào đầu tiên..

Việc gọi đén phương thức này, bởi các level khác của log level (8 level được đề cập bên trên nhé), thì kết quả trả về PHẢI (MUST) có cùng kêt quqar giống như việc gọi phương thức ở level-specific.

VIệc gọi phương thức không được định nghĩa ở specification PHẢI ném ra một Psr\Log\InvalidArgumentException nếu việc cái đặt không biết nó ower level nào. Người dùng KHÔNG NÊN(SHOULD NOT) sử dụng một custom level nếu không có những hiểu biết chắc chắn về việc cài đặt và hỗ trợ nó.

Messages

Mọi phương thức đều chấp nhận một string và string này được coi là message, hoặc một object có phương thức __toString().

Hiểu nôm nay như này, :, các phương thức đều phải chấp nhận một tham số là một string hoặc một object có khả năng chuyển đổi nó sang string. Để làm gì? để ghi log với message tương ứng nếu người dùng muốn.

Kiểu nói, Ê, ghi cho anh rằng giáng sinh năm 2017 anh không có gấu, :crazy_face:, như vậy, thì nội dung giáng sinh 2017 anh không có gấu là nội dung message. và mọi hàm để ghi log, phải luôn luôn phải chấp nhận một tham số là string, được hiểu để lưu trữ thông tin message khi cần. Người cài đặt (implementor) CÓ THỂ (MAY) phải handing trường hợp đặc biệt các object có khả năng _toString(), trong trường hợp đó, thì bản chất việc của những Implementor là convert từ object sang string bằng cách gọi object->toString(). :man_gesturing_ok:
Message CÓ THỂ (MAY) tồn tại placeholder, và nó có thể được thay thế bởi giá trị trong context array, trong những trường hợp cụ thể bởi implementor. Nhắc lại khái niệm implementor ở .
- Các tên placeholder PHẢI(MUST) có key tương tứng trong context array
- Các tên placeholder PHẢI (MUST) được ngăn cách nhau bởi một cặp **{ ** và }. nghĩa là hiểu nôm na nó sẽ như này, {placeholder1}{placeholder2}
- Các tên placeholder NÊN(SHOULD) bao gồm các ký từ A-Z, a-z, 0-9, dấu gạch dưới (underscore) và dấu chấm. Việc sử dụng những ký tự khác phải được mô tả rõ ràng trong placeholder specification
- Implementor CÓ THỂ(MAY) sử dụng các placeholder để cài đặt việc translate logs hoặc hiển thị các logs. Người dùng (users) KHÔNG NÊN (SHOULD NOT) động đến các placeholder khi họ có thể không biết cái nào trong context array sẽ được hiển thị. Mà thường, chúng ta thường comment trong code một đoạn có nội dung là, ĐỪNG ĐỘNG VÀO CHỖ CODE NÀY KHI YOU CHƯA THỰC SỰ HIỂU NÓ ĐANG LÀM GÌ, VÀ KHI HIỂU RỒI, HÃY LIÊN HỆ VỚI I KHI MUỐN THAY ĐỔI, CTA NÊN CÓ CUỘC CHIẾN GIỮA HAI NGƯỜI ĐÀN ÔNG VỚI NHAU
```
  <?php

  /**
   * Interpolates context values into the message placeholders.
   */
  function interpolate($message, array $context = array())
  {
      // build a replacement array with braces around the context keys
      $replace = array();
      foreach ($context as $key => $val) {
          // check that the value can be casted to string
          if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) {
              $replace['{' . $key . '}'] = $val;
          }
      }

      // interpolate replacement values into the message and return
      return strtr($message, $replace);
  }

  // a message with brace-delimited placeholder names
  $message = "User {username} created";

  // a context array of placeholder names => replacement values
  $context = array('username' => 'bolivar');

  // echoes "User bolivar created"
  echo interpolate($message, $context);
  ```
```

Context

Mọi phương thức đều phải chấp nhận một array được gọi là context data, Nó lưu trữ các thông tin, mà không thể hiện được đơn giản bằng String. Một mảng có thể tồn tại bất kỳ thứ gì. Người cài đặt (implementor) PHẢI (MUST) chắc chắn rằng context data phải xử lý được càng nhiều trường hợp càng tốt. Với một giá trị trong context, phải vào các trường hợp tung ra một exception, hoặc một error, warning, hay notice.
Nếu một Exception object được đưa vào context data, nó phải là một 'exception' key. Logging một exception là một pattern phổ biến, nó cho phép người cài đặt đưa các exception vào một stack , và để back-end support chúng. Người cài đặt PHẢI (MUST) chắc chắn rằng key 'exception' đã được sử dụng, nó CÓ THỂ (MAY) chứa đựng bất kỳ thứ gì.

Các class helper và interfaces

Psr\Log\AbstractLogger class cung cấp những cài đặt cho LoggerInterface, nó rất dễ dàng để kế thừa và cài đặt các phương thức log thông thường.
Tương tự, sử dụng Psr\Log\LoggerTrait sử dụng để cài đặt những phương thức log thông thường. Tham khảo Trait trong php
Psr\Log\NullLogger được cung cấp cùng với interface, có thể sử dụng bởi người dùng để cung cấp cách để cài đặt những trường hợp mà không có log để ghi vào. Tuy nhiên, điều kiện log, có thể tốt hơn khi để nó trong context data.
Psr\Log\LoggerAwareInterface chỉ tồn tại duy nhất phương thức *setLogger(LoggerInterface $logger), dùng để tự động tạo các thể hiện của một logger.
Psr\Log\LoggerAwareTrait có thể sử dụng để cài đặt các interface với bất kỳ một class nào, bạn có thể truy cập nó bằng cách $this->logger;
Psr\Log\LogLevel class lưu trữ các hằng số cho 8 log level như đã đề cập.

Package

Các interfaces và các class đều được miêu tả rõ ràng cùng với những exception và test suite để kiểm tra việc cài đặt của bạn. Có thể xem chi tiết tại đây
Dưới đây là các bài class và interface đã được đề cập ở trên.

Psr\Log\LoggerInterface

<?php

namespace Psr\Log;

/**
 * Describes a logger instance
 *
 * The message MUST be a string or object implementing __toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context array can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Exception instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 */
interface LoggerInterface
{
    /**
     * System is unusable.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function emergency($message, array $context = array());

    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function alert($message, array $context = array());

    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function critical($message, array $context = array());

    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function error($message, array $context = array());

    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function warning($message, array $context = array());

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

    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function info($message, array $context = array());

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

    /**
     * Logs with an arbitrary 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;

/**
 * Describes a logger-aware instance
 */
interface LoggerAwareInterface
{
    /**
     * Sets a logger instance on the object
     *
     * @param LoggerInterface $logger
     * @return null
     */
    public function setLogger(LoggerInterface $logger);
}

Psr\Log\LogLevel

<?php

namespace Psr\Log;

/**
 * Describes log levels
 */
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';
}

Tham khảo thêm tại đây.