README

PHP项目中简单的HTTP请求、响应和错误日志记录器。它可以与不同类型的中间件（取决于框架或库）以及纯PHP项目一起使用。

入门

先决条件

本指南假设您正在使用（或计划使用）以下技术进行项目

• PHP 7.1+
• Composer

安装

1. 首先，确保您已经安装并配置了一个运行中的Web服务器（如Apache），并使用PHP 7.1或更高版本。
2. 使用 composer 安装库： composer require tribeos/http-log

基本用法

在使用库之前，您必须首先引入生成的 autoload.php 文件

require_once "vendor/autoload.php";

之后，您可以在项目中使用所需的 HttpLog\* 命名空间和函数。

为了开始记录HTTP请求和响应，您需要首先创建一个 HttpLogger 对象。对象构造函数有三个必需参数，一个可选的第四个参数

1. type：记录器类型（目前仅支持文件记录器；SQL和MongoDB记录器计划在以后添加；默认值：file）
2. filter：日志过滤器。它表示哪些请求/响应属性将被记录（默认值：full+h = 所有支持属性 + 请求和响应头）（查看更多）
   • 具有几个默认过滤器配置，以及定义自定义过滤器的选项
3. path：日志文件的路径（默认值：logs/debug.log）
   • 确保您的目标文件夹 存在，并且您具有正确的 写入权限。
   • 注意：任何自定义路径都可以指定，但它 必须 以 绝对路径 的形式（例如，使用 __DIR__）指定到项目根目录。原因是某些可能由库触发的PHP函数会更改执行路径，因此我们必须依赖于绝对路径。
4. default_log （可选）：控制错误是否也会记录到默认的Apache/PHP日志文件（默认值：true）
   • 该库按设计将所有错误记录到指定的 path 文件。使用 default_log 参数，您还可以让所有错误记录到默认的错误日志文件，此外 记录到库的日志文件。
   • 注意：致命PHP错误（不可恢复的）始终记录到默认错误日志文件，不受此参数影响。

示例记录器初始化如下

require_once __DIR__."/vendor/autoload.php";
/* Use the logger namespace */
use HttpLog\HttpLogger;

$logger = HttpLogger::create("file", "full+h", "logs/debug.log", false)::get();

HttpLogger::create() 构建记录器的静态实例（以后可以在代码的任何地方重用），而 HttpLogger::get() 返回新创建的记录器实例。

这些方法可以像上面示例中那样链接，也可以单独调用，如下所示

HttpLogger::create("file", "full+h", "logs/debug.log", false);
/* The HttpLogger::get() can then be called from anywhere inside the project. */
$logger = HttpLogger::get();

记录器初始化后，记录器就准备好使用了。根据项目需求和使用的技术，您可以在响应输出结束时或在设置在API响应发送后触发的特定中间件中调用 log() 方法。

• 注意：这是推荐的做法。理论上可以在响应之前从其他地方调用记录器，但那样的话，它将无法 捕获和记录响应输出。此外，还可能出现其他意外的行为。

/* Pure PHP example  */

require_once __DIR__."/vendor/autoload.php";
use HttpLog\HttpLogger;

/* Create and fetch the logger instance */
$logger = HttpLogger::create("file", "full+h", "logs/debug.log", false)::get();

/* Output a response */
header("Content-Type: application/json");
echo json_encode( ["param" => "test"] );

/* Log the incoming request, outgoing response and possible errors */
$logger->log();

日志格式

日志文件格式化为一个 TSV文本文件，其中所有日志参数通过制表符（\t）分隔，便于解析和格式化。每个请求/响应“对”在文件中用一行表示，从请求时间开始，接着是请求数据、响应数据以及遇到的任何错误。

示例（通过Postman发送）

2019-03-12 21:05:31	/http-logger	/?param=test	https:///http-logger?param=test	GET	::1	36360	HTTP/1.1	PostmanRuntime/7.6.0		0	*/*	{"param":"test"}	[]	[]	[]	0	0	{"test_header":"test_value","cache-control":"no-cache","Postman-Token":"a84d2d58-3f77-4c39-a60d-a06487a6cdc8","User-Agent":"PostmanRuntime\/7.6.0","Accept":"*\/*","accept-encoding":"gzip, deflate","referer":"http:\/\/localhost\/http-logger?param=test","Host":"localhost","Connection":"keep-alive"}	200	{"param":"test"}	{"Keep-Alive":"timeout=5, max=99","Connection":"Keep-Alive","Transfer-Encoding":"chunked","Content-Type":"application\/json"}

已记录参数

以下参数可用于记录（并在默认配置中使用）

• date：请求发生的确切时间
• base：URL的父子目录
• url：请求的URL
• referrer：引用URL
• method：请求方法（GET、POST、PUT、DELETE等）
• ip：客户端的IP地址
• port：客户端访问端口
• scheme：服务器协议（HTTP/HTTPS）
• user_agent：浏览器信息
• type：内容类型
• length：内容长度
• accept：HTTP接受参数
• query：查询字符串参数
• data：POST参数
• cookies：Cookie参数
• files：上传的文件
• is_https：连接是否安全（HTTPS）
• is_ajax：请求是否为AJAX请求
• request_headers：HTTP请求头
• code：HTTP响应代码
• body：HTTP响应体
• response_headers：HTTP响应头

过滤器

该库允许对记录器应用不同的日志过滤器。过滤器（作为记录器创建中的第二个参数指定）指定了上述哪些参数将被记录（以及顺序）。

每个内置过滤器都有两种变体：基本变体和头部变体。基本变体包括与该过滤器相关的所有参数，除了完整的头部信息（request_headers和response_headers不存在）。头部变体包含参数和所有头部信息。

可用的（基本变体）过滤器包括

• standard：包括date、url、method、ip、query、data、code、body
• full：所有可记录的属性（如上面所示）
• request_only：仅请求属性（所有属性除code和body外）
• response_only：仅响应属性（code和body）
• error：仅记录遇到的错误（通知、警告和错误）（更多）

这些过滤器（除error外）还有头部变体（standard+h、full+h、request_only+h、response_only+h），包括额外的头部信息（请求属性之后是请求头，响应属性之后是响应头）。

库中默认设置为full+h过滤器，这意味着记录器将存储所有请求和响应数据，以及请求和响应头。

自定义过滤器

该库允许创建自定义过滤器，使用户能够设置他们想要记录的特定属性及其顺序。

自定义过滤器定义如下：property1|property2|property3|...（属性通过竖线符号|分隔）。

当由记录器解析时，仅记录自定义过滤器中指定的属性，忽略其他属性。

示例

/* Defining a logger with a custom filter */
$logger = HttpLogger::create("file", "date|url|method|ip|", "logs/debug.log", false)::get();

本示例中的记录器将只记录请求日期、请求URL、请求方法和客户端的IP地址，且顺序固定。

错误记录

除了请求和响应记录外，该库还具备错误拦截和处理功能。库能够记录并优雅地处理PHP的通知、警告、错误和致命错误。错误将以编码后的JSON字符串形式记录在请求和响应数据之后的同一行。

• 注意：为了简化，在本文档的其余部分，我们将使用“错误”一词来指代所有通知、警告和错误，除非明确说明。

示例

2019-03-12 22:07:11	/http-logger	/?param=test	https:///http-logger?param=test	GET	::1	37714	HTTP/1.1	PostmanRuntime/7.6.0		0	*/*	{"param":"test"}	[]	[]	[]	0	0	{"test_header":"test_value","cache-control":"no-cache","Postman-Token":"3a41e974-4f0c-49e6-8af3-3942ecd25f80","User-Agent":"PostmanRuntime\/7.6.0","Accept":"*\/*","accept-encoding":"gzip, deflate","referer":"http:\/\/localhost\/http-logger?param=test","Host":"localhost","Connection":"keep-alive"}	500		{"Connection":"close","Content-Type":"application\/json"}	[{"error_type":"NOTICE","log_level":5,"error_code":8,"description":"Undefined variable: undefined","file":"\/var\/www\/html\/http-logger\/index.php","line":13},{"error_type":"INFO","log_level":6,"error_code":1024,"description":"This is an informational message.","file":"\/var\/www\/html\/http-logger\/index.php","line":15},{"error_type":"FATAL","log_level":3,"error_code":1,"description":"Uncaught Error: Call to undefined function no_such_function() in \/var\/www\/html\/http-logger\/index.php:17\nStack trace:\n#0 {main}\n  thrown","file":"\/var\/www\/html\/http-logger\/index.php","line":17}]

如何处理错误？

在请求/响应生命周期中，PHP脚本被允许执行。记录器将其其中一个方法设置为错误处理器（通过set_error_handler()），并拦截任何异常流程。

遇到的所有错误都存储在记录器的错误堆栈（数组）中，并在调用log()方法后，所有错误都记录在请求和响应数据的同一行，便于轻松审查执行期间可能发生的异常流程。

通知和警告将被存储在错误堆栈中，并且脚本将正常执行，直到执行记录操作和脚本自然结束。然而，严重错误（用户错误和致命PHP错误）在被记录后，将在发生时停止脚本的执行，并返回一个包含致命错误详情的格式化JSON响应给用户。

错误对象包含以下参数（所有这些都将被记录）

• error_type：捕获到的错误类型（通知、警告、错误等）
• log_level：错误的记录级别
• error_code：错误代码
• description：捕获到的错误的消息描述
• file：错误发生的文件
• line：错误发生的行

error 过滤器

一些用户可能只关心遇到的错误，而不一定关心请求和响应数据。因此，在记录器初始化过程中可以应用error过滤器。

应用了error过滤器后，只记录错误，以TSV格式（与其他过滤器中格式化的JSON相对）记录。此外，每个错误将单独记录一行，并包含一个date属性。

/* Create and fetch an error-only logger instance */
$logger = HttpLogger::create("file", "error", "logs/debug.log", false)::get();

print_r($undefined);
md5();
no_such_function();

生成的日志

2019-03-12 21:55:25	NOTICE	5	8	Undefined variable: undefined	/var/www/html/http-logger/index.php	13
2019-03-12 21:55:25	WARNING	4	2	md5() expects at least 1 parameter, 0 given	/var/www/html/http-logger/index.php	14
2019-03-12 21:55:25	FATAL	3	1	Uncaught Error: Call to undefined function no_such_function() in /var/www/html/http-logger/index.php:17 Stack trace: #0 {main}   thrown	/var/www/html/http-logger/index.php	17

用户定义的错误

除了自动管理遇到的错误外，该库还允许用户在任何项目位置记录自定义错误消息（类似于Log4j的工作方式）。

库包含以下记录方法，这些方法可以从记录器对象中调用

• debug()
• info()
• warning()
• error()
• fatal()

示例

/* Create and fetch the logger instance */
$logger = HttpLogger::create("file", "full+h", "logs/debug.log", false)::get();

$logger->warning("Testing a sample warning.");
$logger->info("This is an informational message.");
$logger->fatal("This fatal error will stop program execution.");

这些用户定义的错误“表现”与常规错误相同：调试消息、警告和信息消息只是被记录，而错误和致命错误也会停止程序执行。此外，记录器将能够在单个会话中轻松记录常规错误和用户定义的错误。

• 注意：由于记录器库的主要目的是请求/响应记录，因此用户仍然需要在代码中某个位置调用$logger->log()或HttpLogger::get()->log()。用户定义的函数将仅在记录器对象中存储日志。实际上将日志提交到文件的log()方法是。

如果记录器初始化中的default_log参数设置为true，用户定义的错误也将记录在默认的Apache/PHP日志文件中。

/* Create and fetch an error-only logger instance */
$logger = HttpLogger::create("file", "error", "logs/debug.log", false)::get();

/* A mix of regular and user-defined errors */
$logger->info("This is an informational message.");
print_r($undefined_variable);
$logger->fatal("This is a fatal error.");

生成的日志

2019-03-12 22:15:55	INFO	6	1024	This is an informational message.	/var/www/html/http-logger/index.php	15
2019-03-12 22:15:55	NOTICE	5	8	Undefined variable: undefined_variable	/var/www/html/http-logger/index.php	13
2019-03-12 22:15:55	FATAL	3	256	This is a fatal error.	/var/www/html/http-logger/index.php	16

附加信息和备注

• 强烈建议在使用此库时不要使用 ini_set('display_errors', 1)，因为这个设置会导致所有错误都进入响应体缓冲区，污染您的响应日志。但是，如果您不关心响应日志，则可以使用此设置。
• 我们的建议是在日志初始化期间将 default_log 参数设置为 false 以禁用默认的PHP日志记录，因为所有信息（甚至比默认日志更详细）都将保存在库的日志文件中，我们希望避免数据冗余。但是，如果您的需求需要，您可以使用两个日志记录器而不存在问题。

库文档

详细的文档可以在以下网址找到： https://aldin-sxr.github.io/http-logger/

文档是用 PHPDocumentor 生成的。

作者

• Aldin Kovačević，库和文档的初始工作 - Aldin-SXR

致谢

• Adnan Miljković，为其在实现某些功能方面的专业建议和建议 - adnanmiljkovic
• Dino Kečo，鼓励我首先创建此库 - dinokeco

许可证

框架是在 MIT 许可证下发布的。有关详细信息，请参阅 LICENSE 文件。

正在进行中 by tribeOS - 世界上最公平、最有利可图的广告市场。