README

已弃用

该 joomla/log 包已被弃用。没有计划进行进一步更新。

简介

Joomla 框架包含一个日志包，允许以可配置的、钩子驱动的形式将日志记录到各种格式。

日志包中包含的类有 Joomla\Log\Log、Joomla\Log\LogEntry、Joomla\Log\AbstractLogger 以及支持格式化和存储的类 Joomla\Log\Logger\Callback、Joomla\Log\Logger\Database、Joomla\Log\Logger\Echoo、Joomla\Log\Logger\FormattedText、Joomla\Log\Logger\Syslog 和 Joomla\Log\Logger\W3c。在这些类中，你通常只会在你项目中使用 Joomla\Log\Log。

日志记录是一个两步过程。

首先，你必须添加监听日志消息的记录器。可以根据优先级和类别配置任意数量的记录器来监听日志消息。例如，你可以配置所有日志消息都记录到数据库中，但只需错误消息记录到文件中。为此，你将使用 Joomla\Log\Log::addLogger 方法。

在至少配置了一个记录器之后，你可以使用 Joomla\Log\Log::addLogEntry 方法添加消息，其中你可以指定一个消息，以及可选的优先级（整数）、类别（字符串）和日期。

日志记录优先级

在我们查看任何日志记录示例之前，我们需要了解优先级是什么。优先级是一个整数掩码，它使用一个或多个在 Joomla\Log\Log 类中预定义的常量设置。这些是

• Joomla\Log\Log::EMERGENCY
• Joomla\Log\Log::ALERT
• Joomla\Log\Log::CRITICAL
• Joomla\Log\Log::ERROR
• Joomla\Log\Log::WARNING
• Joomla\Log\Log::NOTICE
• Joomla\Log\Log::INFO
• Joomla\Log\Log::DEBUG

有关每个常量在何种情况下使用的详细信息，请参阅 PSR-3（第 3 部分）的详细信息，在此 - https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md#3-psrlogloggerinterface，其中可以找到详细说明。

还有一个最终的常量，Joomla\Log\Log::ALL，它对应于十六进制的 FFFF（16 位）。其他常量保留前八个位用于系统使用。这允许开发者使用十六进制的 100 到 8000 的最后八个位，如果需要的话，用于自定义使用。由于这些值是用于掩码的，因此可以使用任何位运算符（与、或、非和异或）进行混合。

默认情况下，记录器将添加到监听 Joomla\Log\Log::ALL 优先级，并且使用 Joomla\Log\Log::INFO 掩码添加日志条目。

将日志记录到文件 （formattedtext）

日志记录的一个非常典型的例子是将日志记录到文件，这是日志记录的默认处理程序。要这样做，请添加记录器，然后你可以添加日志消息。

// Initialise a basic logger with no options (once only).
Joomla\Log\Log::addLogger(array());

// Add a message.
Joomla\Log\Log::add('Logged');

由于在 Joomla\Log\Log::addLogger 调用中没有指定记录器，因此将使用“formattedtext”记录器。这将消息记录到“log_path”配置变量指定的日志文件夹中的“error.php”文件中（在 Joomla CMS 中，默认为 /logs/）。它看起来可能像这样

#<?php die('Forbidden.'); ?>
#Date: 2011-06-17 02:56:21 UTC
#Software: Joomla Framework 01-Jun-2011 06:00 GMT

#Fields: datetime   priority    category    message
2011-06-17T03:06:44+00:00   INFO    -   Logged

文件是制表符分隔的，默认列包括时间戳、优先级的文本表示、类别以及最后的信息。由于我们没有提供它，类别为空（一个破折号）。

要记录不同的优先级，你可以使用以下代码：

Joomla\Log\Log::add('Logged 3', Joomla\Log\Log::WARNING, 'Test');

日志文件现在看起来类似于以下内容：

2011-06-17T03:06:44+00:00 INFO - Logged
2011-06-17T03:52:08+00:00 WARNING - Logged 2
2011-06-17T03:57:03+00:00 WARNING test Logged 3

带有 formattedtext 的附加选项

当添加 "formattedtext" 记录器时，以下选项可用，可以在传递给 Joomla\Log\Log::addLogger 的数组中提供。

更改日志文件名

根据上一节中概述的选项，当你添加记录器时，你可以更改日志文件名，如下所示：

// Log to a specific text file.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'mylogs.php'
	)
);

将不同优先级记录到不同文件

通过添加绑定不同日志优先级到不同文件的多个记录器，你可以将不同类型的消息记录到不同的文件中。例如，以下代码将记录所有消息（除错误外）到一个文件中，并将错误消息记录到另一个文件中。

// Log all message except errors to mylogs.php.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'mylogs.php'
	),
	Joomla\Log\Log::ALL ^ Joomla\Log\Log::ERROR
);

// Log errors to myerrors.php.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'myerrors.php'
	),
	Joomla\Log\Log::ERROR
);

将特定类别记录到文件

如果你希望收集特定项目、类或扩展的错误，你也可以将日志绑定到不同的类别。例如，以下代码可以用于 Joomla 扩展，仅收集与其相关的错误。

// Log my extension errors only.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'com_hello.errors.php'
	),
	Joomla\Log\Log::ERROR,
	'com_hello'
);

要记录消息到该记录器，你可以使用以下类似的代码：

Joomla\Log\Log::add('Forgot to say goodbye', Joomla\Log\Log::ERROR, 'com_hello');

需要注意的是，其他超出你控制的记录器也可能捕获到这条消息。

按日期分割日志

随着时间的推移，日志文件可能会变得非常长。一个方便的解决方案是将日志滚动到基于时间段的不同的文件中 - 一个小时、一天、一个月甚至一年。要这样做，你只需要将日期添加到日志文件的文件名中。以下示例显示了如何按日这样做。

// Get the date.
$date = date('Y-m-d');

// Add the logger.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'com_hello.'.$date.'.php'
	)
);

更改日志消息的格式

当你添加日志消息时，它以以下默认格式写入文件：

{DATETIME} {PRIORITY} {CATEGORY} {MESSAGE}

每个字段都以大写形式书写，用花括号括起来，并用制表符分隔。在 "formattedtext" 记录器中定义了许多其他自动定义的字段，你可以利用这些字段。这些是：

要修改日志格式以添加任何或所有这些字段，你可以按以下代码添加记录器。

// Add the logger.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'com_hello.php',
		'text_entry_format' => '{DATE} {TIME} {CLIENTIP} {CATEGORY} {MESSAGE}'
	)
);

如你所见，你可以根据项目的需求包括或排除任何字段。

你也可以添加更多字段，但要这样做，你需要直接创建并添加一个 Joomla\Log\LogEntry 对象。以下示例显示了如何这样做。

// Add the logger.
Joomla\Log\Log::addLogger(
	array(
		'text_file' => 'com_shop.sales.php',
		'text_entry_format' => '{DATETIME} {PRICE} {QUANTITY} {MESSAGE}'
	),
	Joomla\Log\Log::INFO,
	'Shop'
);

$logEntry = new Joomla\Log\LogEntry('T- Shirt', Joomla\Log\Log::INFO, 'Shop');
$logEntry->price = '7.99';
$logEntry->quantity = 10;

Joomla\Log\Log::add($logEntry);

强烈建议在使用自定义格式时，将日志条目绑定到特定且唯一的类别，否则具有不同格式（字段）的日志文件可能会混合。

将日志记录到数据库

"database" 记录器允许你将消息记录到数据库表。默认表的创建语法如下：

CREATE TABLE `jos_log_entries` (
	`priority` int(11) DEFAULT NULL,
	`message` varchar(512) DEFAULT NULL,
	`date` datetime DEFAULT NULL,
	`category` varchar(255) DEFAULT NULL,
	KEY `idx_category_date_priority` (`category`,`date`,`priority`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

使用 "database" 记录器记录消息的以下代码作为指南。

// Add the logger.
Joomla\Log\Log::addLogger(
	array(
		'logger' => 'database'
	),
	Joomla\Log\Log::ALL,
	'dblog'
);

// Add the message.
Joomla\Log\Log::add('Database log', Joomla\Log\Log::INFO, 'dblog');

请注意，示例将记录器绑定到所有消息优先级，但仅绑定到类别为 "dblog" 的那些。

如果你想在消息中存储附加信息，你可以使用 JSON 编码的字符串来做到这一点。例如：

// Assemble the log message. Assume a $user object.
$log = array(
	'userId' => $user->get('id'),
	'userName' => $user->get('name'),
	'stockId' => 'SKU123',
	'price' => '7.49',
	'quantity' => 10
);

// Add the message.
Joomla\Log\Log::add(json_encode($log), Joomla\Log\Log::INFO, 'dblog');

这使得检索详细信息的显示成为可能。

通过 Composer 安装

将 "joomla/log": "~1.0" 添加到 composer.json 中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/log": "~1.0"
	}
}

或者，你可以简单地从命令行运行以下内容：

composer require joomla/log "~1.0"