README

远程控制台调试器

将格式化的调试数据输出到控制台运行的调试服务器
Tracy/Symfony调试栏的替代方案，用于调试CLI脚本、后台任务、许多并发请求等。

包含

带有许多有用快捷函数的远程转储器（《Dogma\Debug\Dumper》）
异常处理程序（《..\ExceptionHandler》）
错误处理程序和统计（《ErrorHandler》）
处理进程信号和终止跟踪（《ShutdownHandler》）
请求信息（《RequestHandler》）
资源使用跟踪器（《ResourcesHandler》）
标准输出跟踪器和统计（《OutputHandler》）
SQL io跟踪器和统计（《SqlHandler》）
Redis io跟踪器和统计（《RedisHandler》）
用于调试流io操作的流处理程序（数据、文件、ftp、http、phar、zlib - 《*StreamHandler》）
用于调试流传输上的io操作的处理器（tcp、udp、unix、udg、ssl、tls - 《FilesHandler》）
跟踪各种系统函数组的处理器（curl、dns、mail、设置、syslog）

要求

PHP 7.1+
ext-sockets（也可以在不使用套接字的情况下本地运行）

安装

运行 composer create-project dogma/dogma-debug。

使用

警告：Dogma - Debug 仅用于开发。

它在后台执行一些非常糟糕的事情（例如重写源代码）来实现它的功能，您绝对不应该在生产环境中使用实时数据执行此类操作。

它不是像Tracy/Symfony/Laravel错误日志这样的生产调试记录器，它并不旨在取代它们。

在某个本地控制台中运行 php server.php 以显示输出（在端口 1729 上启动套接字服务器）。
将 shortcuts.php 或 client.php 包含到您的代码中，或在使用 php.ini 中的 auto_prepend_file 指令时使用它。
您可以在客户端所在的同一目录中创建 debug-config.php 以配置它。

转储器

转储器具有许多功能和配置选项，可以使转储输出更加紧凑、可读和可用 - 例如

关于转储值的丰富信息（大小、长度、格式化时间戳、标志整数的二进制组件...）
类型的自定义和内置格式化程序
单行模式下的类型自定义和内置格式化程序
转储类和函数的静态成员（调用为 rd(Foo::class) 或 rd([Foo::class, 'method'])）
转储闭包中的绑定值
自定义计时器以及测量给定请求中使用的资源和时间
从文件路径和命名空间中删除已知的前缀
少量项目的单行数组转储
可配置的调用堆栈信息用于转储
自定义颜色配置

函数快捷键

ld($value, ...) - 本地转储
lvd($value, ...) - 使用本地 var_dump() + 一些颜色实现的本地转储
rd($value, ...); - 远程转储
rvd($value, ...); - 使用本地 var_dump() + 一些颜色实现的远程转储
rc($callable, ...) - 远程捕获转储（转储可调用的输出结果）
rb($length, $argsDepth, $codeLines, $codeDepth, $callstack) - 远程回溯转储
rf() - 远程打印函数/方法名称
rl($label, [$name]) - 远程打印用户定义的标签
rt([$name]) - 远程计时器/计数器。显示自上一个事件以来经过的时间
rm([$name]) - 远程内存报告。显示自上一个事件以来消耗/释放的内存
rw($string) - 远程写入。将原始格式化字符串写入调试输出

其他

Dumper::varDump() - 更好格式化和着色 var_dump()

配置

常用

int Dumper::$maxDepth - 要遍历的结构最大深度（默认 3）
int Dumper::$maxLength - 输出字符串的最大长度（以字符为单位）（默认 1000）
int Dumper::$shortArraysMaxLength - 单行输出短数组的最大长度 - 例如 [1, 2, 3]（默认 100）
int Dumper::$shortArrayMaxItems - 单行输出短数组的项目最大计数（默认 20）
bool Dumper::$alwaysShowArrayKeys - 设置为 true 以显示从 0 开始的列表的键（默认 false）
string Dumper::$stringsEncoding - 输出字符串的编码。输出始终是 UTF-8（默认 'utf-8'）
string[] Dumper::$hiddenFields - 从输出中隐藏的字段名称 - 例如 password 等。
bool Dumper::$showInfo - 显示已输出值的扩展信息 - 例如 "ÁČŘ" // 3 ch, 6 B
string Dumper::$infoTimeZone - 从已输出整型/浮点型时间戳格式化可读时间信息的时间区域
int Dumper::$propertyOrder - 对象输出的属性排序。默认为 Dumper::ORDER_VISIBILITY_ALPHABETIC
array<string, string> Dumper::$namespaceReplacements - 用于缩短输出类命名空间的正则表达式和替换映射

跟踪

int Dumper::$traceLength - 输出值的调用栈的行数（默认 1）
bool Dumper::$traceDetails - 在调用栈中显示类和方法（默认 true）
int Dumper::$traceArgsDepth - 调用栈中函数/方法参数的深度（默认 0）
int[] Dumper::$traceCodeLines - 在调用栈中的每个项目显示 n 行代码（默认 [5] - 意味着第一个项目为 5 行，其余为 0）
array{0: string|null $class, 1: string|null $method} Dumper::$traceSkip - 调用栈中要跳过的函数/方法
string[] Dumper::$trimPathPrefix - 要修剪的文件路径前缀列表
- 由 Dumper::trimPathPrefixBefore() 和 Dumper::trimPathPrefixAfter() 配置

格式化程序

bool Dumper::$useFormatters - 切换以使用自定义和内置类型格式化程序（默认 true）
array<class-string, callable> Dumper::$formatters - 自定义和内置类型格式化程序列表
array<class-string, callable> Dumper::$shortFormatters - 当 $maxDepth 达到时单行输出用的自定义和内置类型格式化程序列表
class-string[] Dumper::$doNotTraverse - 禁止遍历的类名称列表（不会污染输出）

输出

array<string, string> Dumper::$colors - 输出着色定义。见特性 DumperFormatters

错误处理器

在请求完成后打印格式化错误/警告/通知，带有调用栈和错误统计信息

通过调用 ErrorHandler::enable($types) 激活

配置

int $types - 处理的错误类型（默认 E_ALL）
bool ErrorHandler::$catch - 切换以捕获错误 - 防止运行默认 PHP 错误处理器（默认 false）
int ErrorHandler::$printLimit - 在远程控制台中显示的错误数量（默认 0）
bool ErorrHandler::$uniqueOnly - 仅显示不同类型的错误（默认 true）
bool ErrorHandler::$listErrors - 在请求结束时列出错误
bool ErrorHandler::$showLastError - 显示可能被另一个错误处理器隐藏的最后错误
bool ErrorHandler::$countMutedErrors - 将用 @ 操作符静音的错误计入统计信息
bool ErrorHandler::$showMutedErrors - 显示用 @ 操作符静音的错误
bool ErrorHandler::$filterTrace - 打开/关闭调用栈过滤（在 Dumper 中配置）
string[][] ErrorHandler::$ignore - 要忽略的错误列表（键是连接类型和消息，项是连接的文件路径后缀和行）
- 例如 ErrorHandler::$ignore = ['Notice: Undefined index "x".' => ['some-file.php:17', 'other-file.php:29']]

ErrorHandler

打印带调用栈的格式化未捕获异常

通过调用 ExceptionHandler::enable() 激活

通过调用 ExceptionHandler::inspectThrownExceptions(...) 激活检查捕获的异常

配置

int ExceptionHandler::$traceLength - 显示调用栈帧的数量（默认 1000）
int ExceptionHandler::$traceArgsDepth - 调用函数/方法时遍历参数的最大深度（默认 1）
int ExceptionHandler::$traceCodeLines - 在输出的调用栈帧中显示的代码行数（默认 5）
int ExceptionHandler::$traceCodeDepth - 显示代码的调用栈帧数量（默认 5）
class-string[] ExceptionHandler::$logExceptions - 检查捕获的异常时记录的异常
class-string[] ExceptionHandler::$notLogExceptions - 检查捕获的异常时不记录的异常
bool ExceptionHandler::$filterTrace - 打开/关闭调用栈过滤（在Dumper中配置）

OutputHandler

报告输出操作（echo）和输出开始

通过调用 OutputHandler::enable() 激活

配置

bool OutputHandler::$printOutput - 打印输出样本（默认 false）
int OutputHandler::$maxLength - 打印输出样本的最大长度（默认 100）

RedisHandler

报告与Redis服务器的通信

目前仅支持通过io流连接的Predis

通过调用 RedisHandler::enableForPredis() 激活

配置

bool RedisHandler::$log - 打开/关闭日志记录（默认 true）
int RedisHandler::$maxLength - 记录消息的最大长度（默认 2000）
bool RedisHandler::$filterTrace - 打开/关闭调用栈过滤（在Dumper中配置）
string[] RedisHandler::$traceFilters - 此处理器特定的附加调用栈过滤

RequestHandler

报告请求输入和输出

无需激活。此处理器仅包含调试器头部和尾部的配置

配置

bool RequestHandler::$showIndex - 在调试器头部显示索引文件名（默认 true）
bool RequestHandler::$requestHeaders - 打印请求头部（默认 false）
bool RequestHandler::$requestCookies - 打印请求cookie（默认 false）
bool RequestHandler::$requestBody - 打印请求体（默认 false）
bool RequestHandler::$stdinData - 显示通过STDIN接收的数据（默认 false）
bool RequestHandler::$responseHeaders - 打印响应头部（默认 false）
bool RequestHandler::$responseCookies - 打印响应cookie（默认 false）
string[] RequestHandler::$methodColors - 调试器头部HTTP方法标签颜色的配置
string[] RequestHandler::$responseColors - 调试器尾部HTTP响应状态标签颜色的配置

ShutdownHandler

报告Linux/Unix上的进程信号（如SIGTERM等）和Windows上的Ctrl-C信号。与ResourcesHandler和Debugger一起尝试确定导致进程终止的原因

通过调用 ShutdownHandler::enable() 激活

SqlHandler

报告SQL数据库查询和事件

目前仅直接支持Dibi抽象层，但您可以注册自己的日志函数

通过在您的数据库层注册回调到SqlHandler::log()激活

配置

int SqlHandler::$logEvent - 要记录的事件类型（默认 SqlHandler::ALL）
bool SqlHandler::$filterTrace - 打开/关闭调用栈过滤（在Dumper中配置）

Stream wrappers

通过在PHP流上注册流处理器来报告PHP流的I/O操作（如fopen()、fwrite()等）

同时通过重写包含文件的源代码和“装饰”原生PHP函数和结构来启用拦截器以执行其操作

包装器

FileStreamWrapper - 在file://或没有方案前缀的文件名上执行I/O操作
PharStreamWrapper - 在phar://上执行I/O操作
HttpStreamWrapper - 在http://和https://上执行I/O操作
FtpStreamWrapper - 在 ftp:// 和 ftps:// 上进行 io 操作
DataStreamWrapper - 在 data:// 上进行 io 操作
PhpStreamWrapper - 在 php:// 上进行 io 操作
ZlibStreamWrapper - 在 zlib:// 和 zip:// 上进行 io 操作

通过调用例如 FileStreamWrapper::enable() 来激活

配置

int FileStreamWrapper::$log - 要记录的 io 操作类型（默认 StreamWrapper::ALL & ~StreamWrapper::INFO）
bool FileStreamWrapper::$logIncludes - 是否记录 PHP include 和 require 的 io 操作（默认 true）
callable FileStreamWrapper::$logFilter - 自定义 io 操作记录的过滤器

其他所有流处理器类似

拦截器

通过在流包装器中实现代码重写魔法，我们可以跟踪或禁用系统函数和构造的使用（如 exit 和 die）

目前实现了以下拦截器

AutoloadInterceptor - 跟踪自动加载函数的使用
CurlInterceptor - 跟踪 Curl 扩展函数的使用
DnsInterceptor - 跟踪 DNS 相关函数的使用
ErrorInterceptor - 跟踪错误/异常相关函数的使用
StreamInterceptor - 跟踪文件系统相关函数的使用。在不支持包装器的流传输（如 tcp、udp、unix、udg、ssl、tls）上很有用
HeadersInterceptor - 跟踪处理 HTTP 标头的函数的使用
Mailinterceptor - 跟踪 mail() 函数的使用
MysqliInterceptor - 跟踪 mysqli 函数的使用并记录 SQL 查询
ProcessInterceptor - 跟踪与进程终止和信号相关的函数的使用
Resourcesinterceptor - 跟踪与资源（时间、内存）相关的函数的使用
SessionInterceptor - 跟踪会话函数的使用
SettingsInterceptor - 跟踪更改 PHP 配置或环境配置的函数的使用
StreamInterceptor - 跟踪流包装器和流过滤器函数的使用
SyslogInterceptor - 跟踪 syslog 函数的使用

有关拦截的本地函数的更完整列表，请参阅 Intercept.php

有了这些处理器，您可以调查任何外部库或您的代码的确切操作内容和时间，而无需在该库中启用某些日志支持，也无需使用 XDebug 等步进调试器

要跟踪尚未覆盖的任何本地 PHP 函数，编写类似处理器非常简单

您可以通过调用 *Interceptor::intercept...() 方法来为函数组激活拦截

当更改拦截配置时，您可能需要清除 opcode 缓存，因为 PHP 代码是在线重写的，PHP 并不知道哪些文件应该重新加载（带有新更改）。当使用 Apache 时，您可以运行例如 service apache2 restart 来完成此操作

作者

Vlasta Neubauer, https://twitter.com/paranoiq

dogma / dogma-debug

维护者

详细信息