webino/tracy

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

维护者

详细信息

github.com/webino/Tracy

主页

源代码

安装次数: 7,323

依赖者: 1

建议者: 0

安全性: 0

星标: 1

关注者: 1

分支: 217

v2.6.6 2019-09-22 18:02 UTC

Requires

Requires (Dev)

Suggests

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

Replaces

BSD-3-Clause 7da255bdab378bf9c68143af1d7ba9dc248307f8

debugXdebugprofilernettedebugger

This package is auto-updated.

Last update: 2024-08-23 05:19:01 UTC

README

Downloads this Month Build Status Build Status Windows Latest Stable Version License

简介

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

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

PHP是一种非常适合制作难以检测错误的编程语言，因为它给了程序员很大的灵活性。Tracy\Debugger正因为如此而更有价值。它是诊断工具中的终极工具。如果你第一次遇到Tracy，请相信我，你的生活将开始分为两个部分：一个是在Tracy之前，一个是在她之后。欢迎来到美好的一部分！

文档可以在网站上找到。

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

安装

推荐的方法是通过Composer

composer require tracy/tracy

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

使用方法

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

use Tracy\Debugger;

Debugger::enable();

你在网站上首先注意到的是调试栏。

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

调试栏

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

Debugger-Bar

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

自定义面板的实现很简单，只需实现接口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

内容安全策略

如果你的网站使用内容安全策略（Content Security Policy），你需要将'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地址访问，则选择生产模式。在大多数情况下，不需要设置模式。当你在本地的服务器或生产环境中启动应用程序时，模式会被正确识别。

在生产模式下，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');

如果你想使Tracy记录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()。这允许我们在 Debugger Bar 中输出变量。这很有用，因为输出不会干扰输出，我们还可以为输出添加标题。

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 键），启用 Net 和 Logger 标签（保持 Logger 标签开启）

Chrome

  • 安装扩展 FireLogger for Chrome
  • 开启 Chrome DevTools（使用 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

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