页面内容

调试工具包

调试工具包¶

调试工具包为 CakePHP 应用程序提供了一个调试工具栏和增强的调试工具。它可以让您快速查看应用程序的配置数据、日志消息、SQL 查询和计时数据。

警告

调试工具包仅供单用户本地开发环境使用。您应该避免在共享开发环境、暂存环境或任何需要隐藏配置数据和环境变量的环境中使用调试工具包。

安装¶

默认情况下，调试工具包与默认的应用程序框架一起安装。如果您已将其删除，并希望重新安装，则可以从应用程序的 ROOT 目录（包含 composer.json 文件的位置）运行以下命令：

php composer.phar require --dev cakephp/debug_kit "~5.0"

然后，您需要执行以下命令来启用该插件：

bin/cake plugin load DebugKit

配置¶

DebugKit.panels - 启用或禁用调试工具包的面板。您可以通过以下方式禁用任何标准面板：
```
// Before loading DebugKit
Configure::write('DebugKit.panels', ['DebugKit.Packages' => false]);
```
DebugKit.includeSchemaReflection - 设置为 true 以启用架构反射查询的记录。默认情况下禁用。
DebugKit.safeTld - 为本地开发设置一个白名单 TLD 数组。这可用于确保调试工具包显示在它判断为不安全的宿主机上。
```
// Allow e.g. http://foo.bar.dev or http://my-shop.local domains locally
Configure::write('DebugKit.safeTld', ['dev', 'local', 'example']);
```

DebugKit.forceEnable - 强制显示调试工具包。小心使用它，通常更安全的方法是简单地将本地 TLD 列入白名单。示例用法：

// Before loading DebugKit
Configure::write('DebugKit.forceEnable', true);

您也可以提供一个可调用对象：

Configure::write('DebugKit.forceEnable', function() {
    return $_SERVER['REMOTE_ADDR'] === '192.168.2.182';
});

DebugKit.ignorePathsPattern - 正则表达式模式（包括分隔符）以忽略路径。调试工具包不会保存与该正则表达式匹配的请求 URL 的数据。默认值为 null
```
// Ignore image paths
Configure::write('DebugKit.ignorePathsPattern', '/\.(jpg|png|gif)$/');
```
DebugKit.ignoreAuthorization - 设置为 true 以忽略调试工具包请求的 Cake 授权插件。默认情况下禁用。
DebugKit.maxDepth - 定义在调试输出中应显示多少级嵌套数据。默认为 5。警告：增加最大深度级别可能会导致内存不足错误。
```
// Show more levels
Configure::write('DebugKit.maxDepth', 8);
```
DebugKit.variablesPanelMaxDepth - 定义在变量选项卡中应显示多少级嵌套数据。默认为 5。警告：增加最大深度级别可能会导致内存不足错误。
```
// Show more levels
Configure::write('DebugKit.variablesPanelMaxDepth', 8);
```

数据库配置¶

默认情况下，调试工具包会将面板数据存储在应用程序 tmp 目录中的 SQLite 数据库中。如果您无法安装 pdo_sqlite，可以通过在 config/app.php 文件的 Datasources 变量中定义 debug_kit 连接来配置调试工具包以使用不同的数据库。例如：

/**
 * The debug_kit connection stores DebugKit meta-data.
 */
'debug_kit' => [
    'className' => 'Cake\Database\Connection',
    'driver' => 'Cake\Database\Driver\Mysql',
    'persistent' => false,
    'host' => 'localhost',
    //'port' => 'nonstandard_port_number',
    'username' => 'dbusername',    // Your DB username here
    'password' => 'dbpassword',    // Your DB password here
    'database' => 'debug_kit',
    'encoding' => 'utf8',
    'timezone' => 'UTC',
    'cacheMetadata' => true,
    'quoteIdentifiers' => false,
    //'init' => ['SET GLOBAL innodb_stats_on_metadata = 0'],
],

您可以随时安全地删除 tmp/debug_kit.sqlite 文件。调试工具包会在需要时重新生成它。

使用历史面板¶

历史面板是调试工具包中最常被误解的功能之一。它提供了一种查看以前请求的工具栏数据的方法，包括错误和重定向。

Screenshot of the history panel in debug kit.

如您所见，该面板包含一个请求列表。在左侧，您可以看到一个标记活动请求的点。点击任何请求数据将加载该请求的面板数据。当加载历史数据时，面板标题将过渡以指示已加载备用数据。

使用邮件面板¶

邮件面板允许您跟踪请求期间发送的所有邮件。

邮件预览让您可以在开发期间轻松检查邮件。

创建预览类¶

为了在发送邮件之前预览邮件，您需要创建一个预览类，该类定义接收者和邮件方法所需的模板变量。

// in src/Mailer/Preview/WelcomePreview.php
namespace App\Mailer\Preview;

use DebugKit\Mailer\MailPreview;

class WelcomePreview extends MailPreview
{
    public function welcome()
    {
        $mailer = $this->getMailer('Welcome');
        // set any template variables receipients for the mailer.

        return $mailer;
    }
}

MailPreview 类应位于应用程序或插件的 Mailer\Preview 命名空间中，并使用 Preview 类后缀。

开发自己的面板¶

您可以为调试工具包创建自己的自定义面板，以帮助调试您的应用程序。

创建面板类¶

面板类只需要放在 src/Panel 目录中即可。文件名应与类名匹配，因此 MyCustomPanel 类预计将有一个名为 src/Panel/MyCustomPanel.php 的文件名。

namespace App\Panel;

use DebugKit\DebugPanel;

/**
 * My Custom Panel
 */
class MyCustomPanel extends DebugPanel
{
    ...
}

请注意，自定义面板需要扩展 DebugPanel 类。

回调¶

默认情况下，面板对象有两个回调，允许它们钩入当前请求。面板订阅 Controller.initialize 和 Controller.shutdown 事件。如果您的面板需要订阅其他事件，您可以使用 implementedEvents() 方法来定义您的面板感兴趣的所有事件。

您应该参考内置面板以获取有关如何构建面板的一些示例。

面板元素¶

预计每个面板都有一个视图元素来呈现面板的内容。元素名称必须是类名的下划线形式。例如，SessionPanel 有一个名为 session_panel.ctp 的元素，SqllogPanel 有一个名为 sqllog_panel.ctp 的元素。这些元素应位于 src/Template/Element 目录的根目录中。

自定义标题和元素¶

面板应该通过约定获取其标题和元素名称。但是，如果您需要选择自定义元素名称或标题，您可以定义方法来定制面板的行为。

title() - 配置在工具栏中显示的标题。
elementName() - 配置应为给定面板使用哪个元素。

面板钩子方法¶

您还可以实现以下钩子方法来定制面板的行为和外观：

shutdown(Event $event) 此方法通常用于收集和准备面板数据。数据通常存储在 $this->_data 中。
summary() 可以返回一个字符串形式的摘要数据，即使面板处于折叠状态，也可以在工具栏中显示。通常是一个计数器或简短的摘要信息。
data() 返回面板数据，作为元素上下文使用。此钩子方法允许您进一步操作在 shutdown() 方法中收集的数据。此方法 **必须** 返回可以序列化的数据。

其他插件中的面板¶

由插件提供的面板几乎与其他插件完全相同，唯一的区别是：您必须将 public $plugin 设置为插件目录的名称，以便在渲染时找到面板的元素。

namespace MyPlugin\Panel;

use DebugKit\DebugPanel;

class MyCustomPanel extends DebugPanel
{
    public $plugin = 'MyPlugin';
        ...
}

要使用插件或应用程序面板，请更新应用程序的 DebugKit 配置以包含该面板

// in src/Application.php bootstrap() method add
Configure::write('DebugKit.panels', ['App', 'MyPlugin.MyCustom']);
$this->addPlugin('DebugKit', ['bootstrap' => true]);

以上将加载所有默认面板，以及来自 MyPlugin 的 AppPanel 和 MyCustomPanel 面板。

辅助函数¶

sql() 转储 ORM 查询的 SQL 语句。
sqld() 转储 ORM 查询的 SQL 语句，并退出。

跟踪查询执行¶

有时您需要知道应用程序中特定查询的执行位置。要获取此类信息，您可以将 SqlTraceTrait 添加到您的 Table 类中，如下所示

use DebugKit\Model\Table\SqlTraceTrait;

class CategoriesTable extends Table
{
    use SqlTraceTrait;
}

这将在 SQL 日志中添加以下信息

/* APP/Controller/CategoriesController.php (line 20) */

B CakePHP 调试工具包 5.x 菜谱

语言

版本

改进此文档

页面内容

调试工具包¶

安装¶

配置¶

数据库配置¶

使用历史面板¶

使用邮件面板¶

创建预览类¶

开发自己的面板¶

创建面板类¶

回调¶

面板元素¶

自定义标题和元素¶

面板钩子方法¶

其他插件中的面板¶

辅助函数¶

跟踪查询执行¶

改进此文档

页面内容

调试工具包¶

安装¶

配置¶

数据库配置¶

工具栏使用¶

使用历史面板¶

使用邮件面板¶

创建预览类¶

开发自己的面板¶

创建面板类¶

回调¶

面板元素¶

自定义标题和元素¶

面板钩子方法¶

其他插件中的面板¶

在没有前端的情况下访问工具栏¶

辅助函数¶

跟踪查询执行¶