# 日志
关于日志接口，PSR规范中给出了相当好的说明和定义，并且有多种细分的日记级别。
## 简化版的日记接口
虽然PSR规范中详尽定义了日志接口，然而在用使用开源框架或内部框架进行项目开发过程中，实际上日记的分类并没有使用得那么丰富，通常只是频繁集中在某几类。为了减少不必要的复杂性，PhalApi特地将此规范的日志接口精简为三种，只有：
+ **error**： 系统异常类日记
+ **info**： 业务纪录类日记
+ **debug**： 开发调试类日记
### error 系统异常类日记
系统异常类日志用于纪录**在后端不应该发生却发生的事情**，即通常所说的系统异常。例如：调用第三方、的接口失败了，此时需要纪录一下当时的场景，以便复查和定位出错的原因。又如：写入一条纪录到数据纪录却失败了，此时需要纪录一下，以便进一步排查。
纪录系统异常日志，用法很简单。可以使用[PhalApi\Logger::error($msg, $data)](https://github.com/phalapi/kernal/blob/master/src/Logger.php#L111)接口，第一个参数$msg用于描述日志信息，第二个可选参数为上下文场景的信息。下面是一些使用示例。
```php
// 只有描述
\PhalApi\DI()->logger->error('fail to insert DB');
// 描述 + 简单的信息
\PhalApi\DI()->logger->error('fail to insert DB', 'try to register user dogstar');
// 描述 + 当时的上下文数据
$data = array('name' => 'dogstar', 'password' => '123456');
\PhalApi\DI()->logger->error('fail to insert DB', $data);
```
上面三条纪录，会在日记文件中生成类似以下的日志内容。
```bash
$ tailf ./runtime/log/201502/20150207.log
2015-02-07 20:37:55|ERROR|fail to insert DB
2015-02-07 20:37:55|ERROR|fail to insert DB|try to register user dogstar
2015-02-07 20:37:55|ERROR|fail to insert DB|{"name":"dogstar","password":"123456"}
```
### info 业务纪录类日记
业务纪录日志，是指纪录业务上关键流程环节的操作，以便发生系统问题后进行回滚处理、问题排查以及数据统计。如在有缓存的情况下，可能数据没及时写入数据库而导致数据丢失或者回档，这里可以通过日记简单查看是否可以恢复。以及说明一下操作发生的背景或原由，如通常游戏中用户的经验值添加：
```php
// 假设：10 + 2 = 12
\PhalApi\DI()->logger->info('add user exp', array('name' => 'dogstar', 'before' => 10, 'addExp' => 2, 'after' => 12, 'reason' => 'help one more phper'));
```
对应的日记为：
```
2015-02-07 20:48:51|INFO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":12,"reason":"help one more phper"}
```
### debug 开发调试类日记
开发调试类日记，主要用于开发过程中的调试。用法如上，这里不再赘述。以下是一些简单的示例。
```php
// 只有描述
\PhalApi\DI()->logger->debug('just for test');
// 描述 + 简单的信息
\PhalApi\DI()->logger->debug('just for test', '一些其他的描述 ...');
// 描述 + 当时的上下文数据
\PhalApi\DI()->logger->debug('just for test', array('name' => 'dogstar', 'password' => '******'));
```
## 更灵活的日志分类
若上面的error、info、debug都不能满足项目的需求时，可以使用[PhalApi\Logger::log($type, $msg, $data)](https://github.com/phalapi/kernal/blob/master/src/Logger.php#L75)接口进行更灵活的日记纪录。
```php
\PhalApi\DI()->logger->log('demo', 'add user exp', array('name' => 'dogstar', 'after' => 12));
\PhalApi\DI()->logger->log('test', 'add user exp', array('name' => 'dogstar', 'after' => 12));
```
对应的日记为：
```
2015-02-07 21:13:27|DEMO|add user exp|{"name":"dogstar","after":12}
2015-02-07 21:15:39|TEST|add user exp|{"name":"dogstar","after":12}
```
注意到，第一个参数为日记分类的名称，在写入日记时会自动转换为大写。其接口函数签名为：
```php
/**
* 日记纪录
*
* 可根据不同需要，将日记写入不同的媒介
*
* @param string $type 日记类型，如：info/debug/error, etc
* @param string $msg 日记关键描述
* @param string/array $data 场景上下文信息
* @return NULL
*/
abstract public function log($type, $msg, $data);
```
## 指定日志级别
在使用日志纪录前，在注册日志```\PhalApi\DI()->logger```服务时须指定开启的日志级别，以便允许指定级别的日志得以纪录，从而达到选择性保存所需要的日志的目的。
通过[PhalApi\Logger](https://github.com/phalapi/kernal/blob/master/src/Logger.php)的构造函数的参数，可以指定日志级别。多个日记级别使用或运算进行组合。
```php
// 日记纪录
$di->logger = new FileLogger(API_ROOT . '/runtime', Logger::LOG_LEVEL_DEBUG | Logger::LOG_LEVEL_INFO | Logger::LOG_LEVEL_ERROR);
```
上面的三类日记分别对应的标识如下。
日志类型|日志级别标识
---|---
error 系统异常类|PhalApi\Logger::LOG_LEVEL_ERROR
info 业务纪录类|PhalApi\Logger::LOG_LEVEL_INFO
debug 开发调试类|PhalApi\Logger::LOG_LEVEL_DEBUG
## 扩展：定制你的日志
普遍情况下，我们认为将日记存放在文件是比较合理的，因为便于查看、管理和统计。当然，如果你的项目需要将日记纪录保存在其他存储媒介中，也可以快速扩展实现的。例如实现数据库的存储思路。
```php
<?php
namespace App\Common\Logger;
use PhalApi\Logger;
class DBLogger extends Logger {
public function log($type, $msg, $data) {
// TODO 数据库的日记写入 ...
}
}
```
随后，重新注册```\PhalApiDI()->logger```服务即可。
```php
$di->logger = new App\Common\Logger\DBLogger(API_ROOT . '/runtime', Logger::LOG_LEVEL_DEBUG | Logger::LOG_LEVEL_INFO | Logger::LOG_LEVEL_ERROR);
```
