dogma / dogma-debug
Powerful remote debugger/dumper
Requires
- php: ^7.1|^8.0
Requires (Dev)
- dogma/dogma: *
- dogma/dogma-dev: 0.1.28
- phpstan/phpstan: 1.4.10
Suggests
- ext-iconv: Any of ext-mb|ext-intl|ext-iconv for unicode strings
- ext-intl: Any of ext-mb|ext-intl|ext-iconv for unicode strings
- ext-mb: Any of ext-mb|ext-intl|ext-iconv for unicode strings
- ext-sockets: If you want to use socket connection (alternatives are log file or printing to stdout)
This package is auto-updated.
Last update: 2024-10-27 17:41:34 UTC
README
Remote console debugger
- outputs beautifully formatted debugging data to debug server running in console
- Tracy/Symfony debug bar alternative for debugging CLI scripts, background tasks, many concurrent requests etc.
includes:
- remote dumper with a lot of useful shortcut functions (
Dogma\Debug\Dumper
) - exception handler (
..\ExceptionHandler
) - error handler and statistics (
ErrorHandler
) - process signals and termination tracker (
ShutdownHandler
) - request info (
RequestHandler
) - resources usage tracker (
ResourcesHandler
) - std output tracker and statistics (
OutputHandler
) - SQL io tracker and statistics (
SqlHandler
) - Redis io tracker and statistics (
RedisHandler
) - stream handlers for debugging stream io operations (data, file, ftp, http, phar, zlib -
*StreamHandler
) - handler for debugging io operations on stream transports (tcp, udp, unix, udg, ssl, tls -
FilesHandler
) - handlers to track various groups of system functions (curl, dns, mail, settings, syslog)
requirements:
- PHP 7.1+
- ext-sockets (also runs locally without sockets)
installation:
Run composer create-project dogma/dogma-debug
.
usage:
WARNING: Dogma - Debug is for development use only.
It does pretty nasty things in the background (like rewriting source code) to accomplish what it does, which you should never do in a production environment with live data.
It is not a production debugging logger like Tracy/Symfony/Laravel error loggers, and it does not aim to replace them.
- Run
php server.php
in some local console for displaying outputs (starts a socket server on port1729
). - Include
shortcuts.php
orclient.php
in your code or use it inauto_prepend_file
directive in yourphp.ini
. - You can create
debug-config.php
in the same directory as client to configure it.
Dumper
Dumper has a lot of features and configuration options to make dump outputs more compact, readable and usable - for example:
- rich information about dumped values (sizes, lengths, formatted time for timestamps, binary components of flag integers...)
- custom and built-in formatters for types
- custom and built-in formatters for types in single-line mode
- dumping static members of classes and functions (call as
rd(Foo::class)
orrd([Foo::class, 'method'])
) - dumping bind values in closures
- custom timer and measuring time and resources used in given request
- trimming known prefixes from file paths and namespaces
- single-line array dumps for arrays with few items
- configurable callstack info for dumps
- custom colors configuration
function shortcuts:
ld($value, ...)
- Local dumplvd($value, ...)
- Local dump implemented with native var_dump() + some colorsrd($value, ...);
- Remote dumprvd($value, ...);
- Remote dump implemented with native var_dump() + some colorsrc($callable, ...)
- Remote capture dump (dumps outputted result of a callable)rb($length, $argsDepth, $codeLines, $codeDepth, $callstack)
- Remote backtrace dumprf()
- Remotely print function/method namerl($label, [$name])
- Remotely print user defined labelrt([$name])
- Remote timer/counter. Shows time since previous eventrm([$name])
- Remote memory report. Shows memory consumed/freed from previous eventrw($string)
- Remote write. Write raw formatted string to debug output
other:
Dumper::varDump()
- better formatted and colorizedvar_dump()
configuration:
common:
int Dumper::$maxDepth
- max depth of the structure to traverse (default3
)int Dumper::$maxLength
- max length of strings to output in characters (default1000
)int Dumper::$shortArraysMaxLength
- max length of short array output on single line - eg[1, 2, 3]
(default100
)int Dumper::$shortArrayMaxItems
- max count of items for short array output on single line (default20
)bool Dumper::$alwaysShowArrayKeys
- set to true to show keys for lists with numeric keys from 0 (defaultfalse
)string Dumper::$stringsEncoding
- encoding of dumped strings. output is always UTF-8 (default'utf-8'
)string[] Dumper::$hiddenFields
- names of fields hidden from output - egpassword
etc.bool Dumper::$showInfo
- show extended info for dumped values - eg"ÁČŘ" // 3 ch, 6 B
string Dumper::$infoTimeZone
- timezone for readable time info formatted from dumped int/float timestampsint Dumper::$propertyOrder
- ordering of properties in object dumps. (default:Dumper::ORDER_VISIBILITY_ALPHABETIC
)array<string, string> Dumper::$namespaceReplacements
- map of regexps and replacements for shortening dumped class namespaces
traces:
int Dumper::$traceLength
- count of lines of call stack for dumped values (default1
)bool Dumper::$traceDetails
- displaying class and method in call stack (defaulttrue
)int Dumper::$traceArgsDepth
- depth of function/method arguments in call stack (default0
)int[] Dumper::$traceCodeLines
- show n lines of code for each item in call stack (default[5]
- meaning 5 lines for firs item, 0 for all others)array{0: string|null $class, 1: string|null $method} Dumper::$traceSkip
- methods/functions to skip in call stackstring[] Dumper::$trimPathPrefix
- list of prefixes of file paths to trim- configurable by
Dumper::trimPathPrefixBefore()
andDumper::trimPathPrefixAfter()
- configurable by
formatters:
bool Dumper::$useFormatters
- switch to use custom and built-in type formatters (defaulttrue
)array<class-string, callable> Dumper::$formatters
- list of custom and built-in type formattersarray<class-string, callable> Dumper::$shortFormatters
- list of custom and built-in type formatters for single line dumps when $maxDepth is reachedclass-string[] Dumper::$doNotTraverse
- list of class names forbidden from traversing (won't pollute output)
output:
array<string, string> Dumper::$colors
- definition of output coloring. see traitDumperFormatters
ErrorHandler
prints formatted errors/warnings/notices with call stack and error statistics when request is finished
activate by calling ErrorHandler::enable($types)
configuration:
int $types
- types of handled errors (defaultE_ALL
)bool ErrorHandler::$catch
- switch to catch errors - prevents running default PHP error handler (defaultfalse
)int ErrorHandler::$printLimit
- count of errors to display in remote console (default0
)bool ErorrHandler::$uniqueOnly
- display only errors of different type (defaulttrue
)bool ErrorHandler::$listErrors
- list errors on end of requestbool ErrorHandler::$showLastError
- show last error which could have been hidden by another error handlerbool ErrorHandler::$countMutedErrors
- count errors muted with @ operator into statisticsbool ErrorHandler::$showMutedErrors
- show errors muted with @ operatorbool ErrorHandler::$filterTrace
- turn on/off callstack filtering (configured in Dumper)string[][] ErrorHandler::$ignore
- list of errors to ignore (keys are concatenated types and messages, items are concatenated file path suffixes and line)- eg
ErrorHandler::$ignore = ['Notice: Undefined index "x".' => ['some-file.php:17', 'other-file.php:29']]
- eg
ExceptionHandler
prints formatted unhandled exceptions with call stack
activate by calling ExceptionHandler::enable()
activate inspecting caught exceptions by calling ExceptionHandler::inspectThrownExceptions(...)
configuration:
int ExceptionHandler::$traceLength
- how many callstack frames to show (default1000
)int ExceptionHandler::$traceArgsDepth
- max depth to traverse for arguments of functions/methods called (default1
)int ExceptionHandler::$traceCodeLines
- lines of code to shown in dumped callstack frames (default5
)int ExceptionHandler::$traceCodeDepth
- for how many callstack frames to show code (default5
)class-string[] ExceptionHandler::$logExceptions
- exceptions to log when inspecting caught exceptionsclass-string[] ExceptionHandler::$notLogExceptions
- exceptions to not log when inspecting caught exceptionsbool ExceptionHandler::$filterTrace
- turn on/off callstack filtering (configured in Dumper)
OutputHandler
reports output operations (echo) and output start
activate by calling OutputHandler::enable()
configuration:
bool OutputHandler::$printOutput
- Print output samples (defaultfalse
)int OutputHandler::$maxLength
- max length of printed output samples (default100
)
RedisHandler:
reports communication with Redis server
for now only Predis connected via io streams is supported
activate by calling RedisHandler::enableForPredis()
configuration:
bool RedisHandler::$log
- Turn logging on/off (defaulttrue
)int RedisHandler::$maxLength
- Max length of logged message (default2000
)bool RedisHandler::$filterTrace
- turn on/off callstack filtering (configured in Dumper)string[] RedisHandler::$traceFilters
- additional callstack filters specific for this handler
RequestHandler
reports request inputs and outputs
no activation needed. this handler only holds configuration for debugger headers and footer
configuration:
bool RequestHandler::$showIndex
- show index file name in debugger header (defaulttrue
)bool RequestHandler::$requestHeaders
- print request headers (defaultfalse
)bool RequestHandler::$requestCookies
- print request cookies (defaultfalse
)bool RequestHandler::$requestBody
- print request body (defaultfalse
)bool RequestHandler::$stdinData
- show data received via STDIN (defaultfalse
)bool RequestHandler::$responseHeaders
- print response headers (defaultfalse
)bool RequestHandler::$responseCookies
- print response cookies (defaultfalse
)string[] RequestHandler::$methodColors
- configuration of HTTP method label colors for debugger headerstring[] RequestHandler::$responseColors
- configuration of HTTP response status label colors for debugger footer
ShutdownHandler
reports process signals like SIGTERM
etc. on Linux/Unix and Ctrl-C
signal on Windows.
together with ResourcesHandler
and Debugger
tries to determine what caused termination of the process
activate by calling ShutdownHandler::enable()
SqlHandler
reports SQL database queries and events
for now only Dibi abstraction layer is supported directly, but you can register your own logging function
activate by registering a callback to SqlHandler::log()
in your DB layer
configuration:
int SqlHandler::$logEvent
- Types of events to log (defaultSqlHandler::ALL
)bool SqlHandler::$filterTrace
- turn on/off callstack filtering (configured in Dumper)
Stream wrappers
wrapper report io operations on PHP streams (fopen()
, fwrite()
etc.) by registering stream handlers on them
also enables interceptors to do their thing by rewriting source code of included files and "decorating" native PHP functions and constructs
wrappers:
FileStreamWrapper
- io operations onfile://
or just file names without schema prefixPharStreamWrapper
- io operations onphar://
HttpStreamWrapper
- io operations onhttp://
andhttps://
FtpStreamWrapper
- io operations onftp://
andftps://
DataStreamWrapper
- io operations ondata://
PhpStreamWrapper
- io operations onphp://
ZlibStreamWrapper
- io operations onzlib://
andzip://
activate by calling e.g. FileStreamWrapper::enable()
configuration:
int FileStreamWrapper::$log
- types of io operations to log (defaultStreamWrapper::ALL & ~StreamWrapper::INFO
)bool FileStreamWrapper::$logIncludes
- switch to log io operations from PHP include and require (defaulttrue
)callable FileStreamWrapper::$logFilter
- custom filter for logging io operations
(similarly for all other stream handlers)
Interceptors
by using source code rewriting witchcraft implemented in stream wrappers, we can track or even disable usage of system functions and constructs (exit
and die
)
implemented interceptors for now:
AutoloadInterceptor
- tracks usage of autoloading functionsCurlInterceptor
- tracks usage of Curl extension functionsDnsInterceptor
- tracks usage of DNS related functionsErrorInterceptor
- track usage of error/exception related functionsStreamInterceptor
- tracks usage of file system related functions. useful on stream transport that do not support wrappers (tcp
,udp
,unix
,udg
,ssl
,tls
)HeadersInterceptor
- tracks usage of functions handling HTTP headersMailinterceptor
- tracks usage ofmail()
functionMysqliInterceptor
- tracks usage of mysqli functions and logs SQL queriesProcessInterceptor
- tracks usage of functions related to process termination and signalsResourcesinterceptor
- tracks usage of functions related to resources (time, memory)SessionInterceptor
- tracks usage of session functionsSettingsInterceptor
- tracks usage of function that change PHP configuration or environment configurationStreamInterceptor
- tracks usage of stream wrapper and stream filter functionsSyslogInterceptor
- tracks usage of syslog functions
see Intercept.php
for more complete list of intercepted native functions
with these handlers you can investigate what and when exactly any foreign library or your code is doing, without the need for some logging support in that library and without having to use stepping debugger like XDebug
it is pretty simple to write other handlers like this to track any native php functions that are not covered yet
you can activate interception for groups of functions by calling *Interceptor::intercept...()
methods
you might want to clear opcode caches when changing interception configuration, because PHP code is rewritten on-the-fly and PHP does not know which files should be reloaded (with new changes). you can run e.g. service apache2 restart
to do this when using apache
Author:
Vlasta Neubauer, https://twitter.com/paranoiq