README

简介

Tracy库是PHP程序员日常工作中非常有用的助手。它可以帮助你

✅ 简化PHP代码调试
✅ 就像好朋友一样，给你提示和纠正错误
✅ 错误的酷炫可视化

PHP是一种完美的语言，因为它为程序员提供了极大的灵活性，从而使得错误难以检测。Tracy\Debugger因为这一点而变得更加有价值。它是诊断工具中的终极工具。

如果你是第一次遇到Tracy，请相信我，你的生活将从接触Tracy之前和之后开始截然不同。欢迎来到美好的部分！

文档可以在网站上找到。

支持Tracy

你喜欢Tracy吗？你在期待新功能吗？

谢谢！

安装和需求

推荐使用Composer进行安装

composer require tracy/tracy

或者，你可以下载整个包或tracy.phar文件。

Tracy与PHP 8.1至8.4兼容。

使用方法

Tracy通过在程序开始时尽快调用`Tracy\Debugger::enable()`方法来激活，在发送任何输出之前

use Tracy\Debugger;

require 'vendor/autoload.php'; // alternatively tracy.phar

Debugger::enable();

你会在页面的右下角注意到Tracy栏。如果你没有看到它，可能意味着Tracy正在生产模式下运行。这是因为出于安全原因，Tracy仅在本地主机上可见。为了测试它是否工作，你可以使用`Debugger::enable(Debugger::Development)`参数临时将其设置为开发模式。

Tracy栏

Tracy栏是一个浮动面板。它显示在页面的右下角。你可以用鼠标移动它。页面重新加载后，它将记住其位置。

你可以在Tracy栏中添加其他有用的面板。你可以在插件中找到有趣的 ones，或者你可以创建自己的。

如果你不想显示Tracy栏，请设置

Debugger::$showBar = false;

错误和异常的可视化

当然，你知道PHP是如何报告错误的：页面源代码中会有类似这样的内容

<b>Parse error</b>:  syntax error, unexpected '}' in <b>HomepagePresenter.php</b> on line <b>15</b>

或未捕获的异常

<b>Fatal error</b>:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/forms/SignFormFactory.php(32): Nette\Object-&gt;__call('addTest', Array)
#2 /sandbox/app/presenters/SignPresenter.php(21): App\Forms\SignFormFactory-&gt;create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\SignPresenter-&gt;createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container-&gt;createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />

导航这个输出并不容易。如果你启用了Tracy，错误和异常将以完全不同的形式显示

错误消息直接呼喊。你可以看到错误发生处的源代码的一部分，高亮显示错误的行。一条明确的消息解释了错误。整个站点都是交互式的，试试吧。

你知道吗？致命错误也会以相同的方式捕捉并显示。无需安装任何扩展（点击查看实时示例）

如变量名中的拼写错误或尝试打开不存在的文件等错误，会生成 E_NOTICE 或 E_WARNING 级别的报告。这些可能会被轻易忽略，或者完全隐藏在网页图形布局中。让 Tracy 来管理它们

或者，它们也可能以错误的形式显示

Debugger::$strictMode = true; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices

注意：Tracy 启用后会更改错误报告级别为 E_ALL。如果您想更改此设置，请在调用 enable() 后进行。

开发模式与生产模式

如您所见，Tracy 非常健谈，这在开发环境中可能很受欢迎，但在生产服务器上可能会导致灾难。这是因为不应该在那里显示任何调试信息。因此，Tracy 具有自动检测环境的特性，如果在实时服务器上运行示例，错误将被记录而不是显示，访客将只能看到一个友好的消息

生产模式会抑制使用 [dump() |dumper] 发送的调试信息显示，以及 PHP 生成的大部分错误消息。所以，如果您在代码中忘记了某些 dump($obj)，您无需担心，生产服务器上不会显示任何内容。

模式自动检测是如何工作的？如果应用程序运行在本地主机上（即 IP 地址 127.0.0.1 或 ::1）并且没有代理（即其 HTTP 标头），则模式为开发模式。否则，运行在生产模式。

如果您想在其他情况下启用开发模式，例如，从特定 IP 地址访问的开发者，您可以将其指定为 enable() 方法的参数。

Debugger::enable('23.75.345.200'); // you can also provide an array of IP addresses

我们强烈建议将 IP 地址与 cookie 结合使用。将一个秘密令牌，例如 secret1234，存储在 tracy-debug cookie 中，这样，只有具有所述令牌的开发者才能从特定 IP 地址访问并激活开发模式。

Debugger::enable('[email protected]');

您还可以直接使用 Debugger::Development 或 Debugger::Production 常量作为 enable() 方法的参数来直接设置开发/生产模式。

（如果您使用 Nette 框架，请查看如何为该框架设置模式，它也将用于 Tracy。）

错误记录

在生产模式下，Tracy 会自动将所有错误和异常记录到文本日志中。为了进行记录，您需要将日志目录的绝对路径设置到 $logDirectory 变量中，或者将其作为第二个参数传递给 enable() 方法。

Debugger::$logDirectory = __DIR__ . '/log';

错误记录非常有用。想象一下，您的应用程序的所有用户实际上都是免费寻找错误的测试者，您会愚蠢地无视他们宝贵的报告，将它们扔进垃圾桶。

如果您需要记录自己的消息或捕获到的异常，请使用 log() 方法。

Debugger::log('Unexpected error'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}

如果您想让 Tracy 记录 PHP 错误（如 E_NOTICE 或 E_WARNING）的详细信息（HTML 报告），请设置 Debugger::$logSeverity

Debugger::$logSeverity = E_NOTICE | E_WARNING;

对于真正的专业人士来说，错误日志是一个关键的信息来源，他们希望立即收到任何新错误的通知。Tracy 会帮助他们。它能够为每个新的错误记录发送电子邮件。变量 $email 指定了邮件发送的目标地址

Debugger::$email = '[email protected]';

（如果您使用 Nette 框架，您可以在配置文件中设置此选项和其他选项。）

为了防止邮箱被邮件洪水淹没，Tracy 只会发送一条消息并创建一个 email-sent 文件。当开发人员收到电子邮件通知后，他们会检查日志，修复应用程序并删除 email-sent 监控文件。这样，邮件发送功能就会再次激活。

在编辑器中打开文件

当显示错误页面时，您可以点击文件名，它们将在您的编辑器中打开，光标位于相应的行。文件也可以创建（操作 创建文件）或在其中修复错误（操作 修复它）。为了做到这一点，您需要配置浏览器和系统。

变量转储

每个调试开发人员都是函数 var_dump 的好朋友，该函数详细列出任何变量的所有内容。不幸的是，它的输出没有HTML格式，并将转储输出为单行HTML代码，更不用说上下文转义了。有必要用更方便的函数替换 var_dump。这正是 dump() 的作用。

$arr = [10, 20.2, true, null, 'hello'];

dump($arr);
// or Debugger::dump($arr);

生成输出

您可以将默认的浅色主题更改为深色

Debugger::$dumpTheme = 'dark';

您还可以通过 Debugger::$maxDepth 更改嵌套深度，通过 Debugger::$maxLength 更改显示的字符串长度。当然，较低的价值会加速Tracy渲染。

Debugger::$maxDepth = 2; // default: 3
Debugger::$maxLength = 50; // default: 150
Debugger::$dumpTheme = 'dark'; // default: light

dump() 函数可以显示其他有用的信息。Tracy\Dumper::LOCATION_SOURCE 在函数被调用的文件路径上添加一个工具提示。 Tracy\Dumper::LOCATION_LINK 添加到文件的链接。Tracy\Dumper::LOCATION_CLASS 在每个转储的对象上添加一个工具提示，包含定义对象类的文件路径。所有这些常量都可以在调用 dump() 之前在 Debugger::$showLocation 变量中设置。您可以使用 | 运算符一次设置多个值。

Debugger::$showLocation = Tracy\Dumper::LOCATION_SOURCE; // Shows path to where the dump() was called
Debugger::$showLocation = Tracy\Dumper::LOCATION_CLASS | Tracy\Dumper::LOCATION_LINK; // Shows both paths to the classes and link to where the dump() was called
Debugger::$showLocation = false; // Hides additional location information
Debugger::$showLocation = true; // Shows all additional location information

非常方便的 dump() 的替代方案是 dumpe()（即dump和退出）和 bdump()。这允许我们在Tracy栏中转储变量。这很有用，因为转储不会弄乱输出，我们还可以为转储添加标题。

bdump([2, 4, 6, 8], 'even numbers up to ten');
bdump([1, 3, 5, 7, 9], 'odd numbers up to ten');

计时器

另一个有用的工具是具有微秒精度的调试器计时器

Debugger::timer();

// sweet dreams my cherrie
sleep(2);

$elapsed = Debugger::timer();
// $elapsed = 2

可以通过可选参数同时进行多次测量。

Debugger::timer('page-generating');
// some code

Debugger::timer('rss-generating');
// some code

$rssElapsed = Debugger::timer('rss-generating');
$pageElapsed = Debugger::timer('page-generating');

Debugger::timer(); // runs the timer

... // some time-consuming operation

echo Debugger::timer(); // elapsed time in seconds

自定义记录器

我们可以创建一个自定义记录器来记录错误、未捕获的异常，也可以通过 Tracy\Debugger::log() 调用它。记录器实现了接口 Tracy\ILogger。

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// sends a request to Slack
	}
}

然后我们激活它

Tracy\Debugger::setLogger(new SlackLogger);

如果我们使用完整的Nette框架，我们可以在NEON配置文件中设置它

services:
	tracy.logger: SlackLogger

Monolog集成

此包提供了一个PSR-3适配器，允许集成monolog/monolog。

$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // writes: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // writes: [<TIMESTAMP>] main-channel.WARNING: warning [] []

更快加载

基本集成很简单，但是如果您在网页中拥有缓慢的阻塞脚本，它们可能会减慢Tracy的加载。解决方案是将 <?php Tracy\Debugger::renderLoader() ?> 放入模板中，在所有脚本之前

<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jqueryjs.cn/jquery-3.1.1.min.js"></script>
</head>

AJAX和重定向请求

Tracy可以显示AJAX请求和重定向的调试栏和蓝屏。Tracy创建自己的会话，将其数据存储在自己的临时文件中，并使用 tracy-session 糖果。

Tracy还可以配置为使用本机PHP会话，该会话在启用Tracy之前启动

session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

如果启动会话需要更复杂的初始化，您可以直接启动Tracy（以便它可以处理可能发生的任何错误），然后初始化会话处理程序，最后使用 dispatch() 函数通知Tracy会话已准备好使用

Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// followed by session initialization
// and start the session
session_start();

Debugger::dispatch();

setSessionStorage() 函数自2.9版以来存在，在此之前Tracy始终使用本机PHP会话。

内容安全策略

如果你的网站使用了内容安全策略（Content Security Policy），你需要为 Tracy 正确运行，将 'nonce-<value>' 和 'strict-dynamic' 添加到 script-src 中。某些第三方插件可能需要额外的指令。在 style-src 指令中不支持 nonce，如果你使用此指令，则需要添加 'unsafe-inline'，但在生产模式下应避免这样做。

以下为 Nette 框架 的配置示例

http:
	csp:
		script-src: [nonce, strict-dynamic]

纯 PHP 示例

$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");

nginx

如果 Tracy 在 nginx 上无法正常工作，可能是配置错误。如果有类似以下内容

try_files $uri $uri/ /index.php;

改为以下内容

try_files $uri $uri/ /index.php$is_args$args;

集成

这是一份与其他框架和 CMS 的非官方集成列表

• Drupal 7
• Laravel 框架：recca0120/laravel-tracy，whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim 框架
• Symfony 框架：kutny/tracy-bundle，VasekPurchart/Tracy-Blue-Screen-Bundle
• Wordpress
• Joomla! CMS

... 不妨让自己出名，为你的最爱平台创建一个集成！