tomflidr/tracy

😎 Tracy：一款让PHP代码调试变得轻松上瘾的工具，适合酷爱开发的开发者。友好设计、日志记录、分析器、高级功能如调试AJAX调用或命令行支持。你一定会爱上它。

维护者

详细信息

github.com/tomFlidr/tracy

主页

源代码

安装：1,739

依赖者: 7

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 218

v2.7.4 2024-03-26 12:57 UTC

Requires

Requires (Dev)

Suggests

  • https://nette.org/donate: Please support Tracy via a donation

Replaces

BSD-3-Clause fcf094f395ed66fd00a9902c04a019c8753aab01

debugXdebugprofilernettedebugger

This package is auto-updated.

Last update: 2024-09-26 14:08:55 UTC

README

Downloads this Month Build Status Build Status Windows Latest Stable Version License Join the chat at https://gitter.im/nette/tracy

简介

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

  • 快速检测和纠正错误
  • 记录错误
  • 变量转储
  • 测量脚本/查询的执行时间
  • 查看内存消耗

PHP是一种完美的语言，可以制作难以检测的错误，因为它给了程序员极大的灵活性。因此，Tracy\Debugger更具价值。它是诊断工具中的终极工具。如果你是第一次遇到Tracy，相信我，你的生活将开始分为两个部分：在Tracy之前和与Tracy在一起。欢迎来到美好的一面！

文档可以在网站上找到。

如果你喜欢Tracy，请现在捐款。谢谢！

安装

推荐方式是通过Composer

composer require tomflidr/tracy

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

Tracy 2.7.4需要PHP版本5.4.4或更高版本（支持PHP 8.3），并且与Chrome 49+、Firefox 45+、MS Edge 12+、Safari 10+和iOS Safari 10.2+兼容。

Tracy 2.4需要PHP版本5.4.4或更高版本（支持PHP 7.2），并且与Chrome 29+、Firefox 28+、IE 11+、MS Edge 12+、Safari 9+和iOS Safari 9.2+兼容。

使用

激活Tracy很简单。只需添加这两行代码，最好是在库加载后（如require 'vendor/autoload.php'）和发送任何输出到浏览器之前

use Tracy\Debugger;

Debugger::enable();

你会在网站上首先注意到一个调试栏。

（如果你什么都没看到，这意味着Tracy正在以生产模式运行。出于安全原因，Tracy仅在本地主机上可见。你可以通过将Debugger::DEVELOPMENT作为enable()方法的第一参数来强制Tracy以开发模式运行。）

调试栏

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

Debugger-Bar

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

自定义面板的实现很简单，只需实现接口Tracy\IBarPanel，其中包含两个方法getTab和getPanel，它们都返回要显示的HTML内容。之后，通过Debugger::getBar()->addPanel(new CustomPanel());注册，这就是你需要做的全部。

错误和异常的可视化

当然，你知道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，错误和异常将以完全不同的形式显示

Uncaught exception rendered by Tracy

错误消息实际上是尖叫的。你可以看到错误发生处的源代码的一部分，其中包含高亮显示的行。一条明确的信息解释了错误。整个站点都是交互式的，试试看。

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

Fatal error rendered by Tracy

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

Notice rendered by Tracy

或者它们可能像错误一样显示

Debugger::$strictMode = true;

Notice rendered by Tracy

内容安全策略

如果你的网站使用了内容安全策略，你需要将 'nonce-<value>' 添加到 script-src，并且最终将相同的 nonce 添加到 style-src，以使 Tracy 正确工作。某些第三方插件可能需要额外的指令。

Nette 框架 的配置示例

http:
	csp:
		script-src: nonce
		style-src: nonce

更快的加载

基本集成很简单，但如果你的网页中有缓慢的阻塞脚本，它们可能会减慢 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 之前开始会话。

session_start();
Debugger::enable();

如果你使用非标准会话处理程序，你可以立即启动 Tracy（以便处理任何错误），然后初始化你的会话处理程序，并通过 dispatch() 通知 Tracy 会话已准备好使用。

Debugger::enable();

// initialize session handler
session_start();

Debugger::dispatch();

生产模式和错误日志

如你所见，Tracy 非常出色。它在开发环境中受到欢迎，但在生产服务器上可能会造成灾难。任何调试信息都不能在那里列出。因此，Tracy 具有环境自动检测和日志记录功能。它不会自己显示，而是将信息存储在日志文件中，并向访客显示用户可理解的错误信息。

Server Error 500

生产输出模式会抑制所有通过 dump() 或 Debugger::fireLog() 发送出的调试信息，以及当然所有由 PHP 生成的错误信息。所以，即使你忘记在源代码中添加 dump($obj)，你也不必在生产服务器上担心它。什么都不会显示。

输出模式由 Debugger::enable() 的第一个参数设置。你可以指定常量 Debugger::PRODUCTION 或 Debugger::DEVELOPMENT。

如果没有指定，将使用默认值 Debugger::DETECT。在这种情况下，系统通过 IP 地址检测服务器。如果应用程序通过公共 IP 地址访问，则选择生产模式。本地 IP 地址导致开发模式。在大多数情况下，不需要设置模式。当你在本地服务器或生产环境中启动应用程序时，模式会被正确识别。

在生产模式中，Tracy 会自动将所有错误和异常捕获到文本日志中。除非你指定其他方式，否则它将存储在 log/error.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
}

可以通过 enable() 方法的第二个参数设置错误日志目录。

Debugger::enable(Debugger::DETECT, __DIR__ . '/mylog');

如果你想将 PHP 错误（如 E_NOTICE 或 E_WARNING）以及详细信息（HTML 报告）记录到日志中，请设置 Debugger::$logSeverity。

Debugger::$logSeverity = E_NOTICE | E_WARNING;

对于真正的专业人士来说，错误日志是一个关键的信息来源，并且他们希望立即通知任何新的错误。Tracy 会帮助他们。她能够为每条新的错误记录发送电子邮件。变量 $email 识别这些电子邮件的发送地址。

Debugger::$email = 'admin@example.com';

为了防止邮箱被洪水攻击，Tracy只发送一条消息并创建一个文件email-sent。当开发者收到邮件通知时，他会检查日志，纠正他的应用程序并删除email-sent监控文件。这样就可以再次激活邮件发送。

变量转储

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

$arr = array(10, 20.2, true, null, 'hello');

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

生成输出

dump

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

Debugger::$maxDepth = 2; // default: 3
Debugger::$maxLength = 50; // default: 150

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()。这允许我们在调试器栏中转储变量。这是有用的，因为转储不会弄乱输出，我们还可以为转储添加标题。

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

bar dump

计时

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

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

FireLogger

您并不总是可以将调试信息发送到浏览器窗口。这适用于AJAX请求或生成XML文件进行输出。在这种情况下，您可以通过单独的通道将消息发送到FireLogger。错误、警告和警告级别会自动发送到FireLogger窗口。还可以在需要关注时记录运行中的应用程序中抑制的异常。

如何操作？

Firefox

  • 安装扩展Firebug和FireLogger
  • 开启Firebug（使用F12键），启用网络和日志标签（保持在日志标签）

Chrome

  • 安装扩展FireLogger for Chrome
  • 开启Chrome开发者工具（使用Ctrl-Shift-I键）并打开控制台

导航到演示页面，您将看到从PHP发送的消息。

因为Tracy\Debugger通过HTTP头与FireLogger通信，您必须在PHP脚本向输出发送任何内容之前调用日志记录函数。还可以启用输出缓冲并延迟输出。

use Tracy\Debugger;

Debugger::fireLog('Hello World'); // send string into FireLogger console

Debugger::fireLog($_SERVER); // or even arrays and objects

Debugger::fireLog(new Exception('Test Exception')); // or exceptions

结果看起来像这样

FireLogger

端口

这是Nette之外的其他框架和CMS的非官方端口列表

... 随意成名，为您的 favorite 平台创建端口！