Provide custom logging and error handling.
Debugger extends PHP's default error handling and gives simpler to use more powerful interfaces.
array<string, mixed>
Runtime config
bool
Whether the config property has already been configured with defaults
array
Holds current output data when outputFormat is false.
array<string, mixed>
Default configuration
string
The current output format.
array<string, array<string, mixed>>
Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
array<string, string|callable>
A map of editors to their link templates.
array<string, class-string>
Mapping for error renderers.
Constructor.
Deletes a single config key.
Reads a config key.
Writes a config key.
Wraps the highlight_string function in case the server API does not implement the function as it is the case of the HipHop interpreter
Add an editor link format
Add an output format or update a format in Debugger.
Add a renderer to the current instance.
Verifies that the application's salt and cipher seed value has been changed from the default value.
Read or write configuration options for the Debugger instance.
Merge provided config with existing config. Unlike config()
which does a recursive merge for nested keys, this method does a simple merge.
Recursively formats and outputs the contents of the supplied variable.
Get a formatted URL for the active editor.
Grabs an excerpt from a file and highlights a given line of code.
Protected export function used to keep track of indentation and recursion.
Export an array type object. Filters out keys used in datasource configuration.
Handles object to node conversion.
Converts a variable to a string for debug output.
Convert the variable to the internal node tree.
Converts a variable to a plain text string.
Format an exception message to be HTML formatted.
Formats a stack trace based on the supplied options.
Returns the config.
Returns the config for this specific key.
Get the configured export formatter or infer one based on the environment.
Returns a reference to the Debugger singleton object instance.
Get the output format for Debugger error rendering.
Get the type of the given variable. Will return the class name for objects.
Creates an entry in the log file. The log entry will contain a stack trace from where it was called. as well as export the variable using exportVar. By default, the log is written to the debug log.
Takes a processed array of data from an error and displays it in the chosen format.
Reads the current output masking.
Prints out debug information about given variable.
Sets the config.
Choose the editor link style you want to use.
Set the output format for Debugger error rendering.
Sets configurable masking of debugger output by property name and array key names.
Outputs a stack trace based on the supplied options.
Shortens file paths by replacing the application base path with 'APP', and the CakePHP core path with 'CORE'.
__construct()
Constructor.
_configDelete(string $key): void
Deletes a single config key.
string
$key Key to delete.
void
Cake\Core\Exception\CakeException
_configRead(string|null $key): mixed
Reads a config key.
string|null
$key Key to read.
mixed
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void
Writes a config key.
array<string, mixed>|string
$key Key to write to.
mixed
$value Value to write.
string|bool
$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
void
Cake\Core\Exception\CakeException
_highlight(string $str): string
Wraps the highlight_string function in case the server API does not implement the function as it is the case of the HipHop interpreter
string
$str The string to convert.
string
addEditor(string $name, Closure|string $template): void
Add an editor link format
Template strings can use the {file}
and {line}
placeholders. Closures templates must return a string, and accept two parameters: The file and line.
string
$name The name of the editor.
Closure|string
$template The string template or closure
void
addFormat(string $format, array $strings): array
Add an output format or update a format in Debugger.
Debugger::addFormat('custom', $data);
Where $data is an array of strings that use Text::insert() variable replacement. The template vars should be in a {:id}
style. An error formatter can have the following keys:
id
, error
, code
, description
, path
, line
, links
, info
code
, context
and trace
. Will be set with the contents of the other template keys.trace
id
, context
code
, context
, help
. See the JS output format for an example.reference
, path
, line
Alternatively if you want to use a custom callback to do all the formatting, you can use the callback key, and provide a callable:
Debugger::addFormat('custom', ['callback' => [$foo, 'outputError']];
The callback can expect two parameters. The first is an array of all the error data. The second contains the formatted strings generated using the other template strings. Keys like info
, links
, code
, context
and trace
will be present depending on the other templates in the format type.
string
$format Format to use, including 'js' for JavaScript-enhanced HTML, 'html' for straight HTML output, or 'txt' for unformatted text.
array
$strings Template strings, or a callback to be used for the output format.
array
addRenderer(string $name, class-stringCake\Error\ErrorRendererInterface> $class): void
Add a renderer to the current instance.
string
$name The alias for the the renderer.
class-stringCake\Error\ErrorRendererInterface>
$class The classname of the renderer to use.
void
checkSecurityKeys(): void
Verifies that the application's salt and cipher seed value has been changed from the default value.
void
configInstance(array<string, mixed>|string|null $key = null, mixed|null $value = null, bool $merge = true): mixed
Read or write configuration options for the Debugger instance.
array<string, mixed>|string|null
$key optional The key to get/set, or a complete array of configs.
mixed|null
$value optional The value to set.
bool
$merge optional Whether to recursively merge or overwrite existing config, defaults to true.
mixed
Cake\Core\Exception\CakeException
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this
Merge provided config with existing config. Unlike config()
which does a recursive merge for nested keys, this method does a simple merge.
Setting a specific value:
$this->configShallow('key', $value);
Setting a nested value:
$this->configShallow('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);
array<string, mixed>|string
$key The key to set, or a complete array of configs.
mixed|null
$value optional The value to set.
$this
dump(mixed $var, int $maxDepth = 3): void
Recursively formats and outputs the contents of the supplied variable.
mixed
$var The variable to dump.
int
$maxDepth optional The depth to output to. Defaults to 3.
void
editorUrl(string $file, int $line): string
Get a formatted URL for the active editor.
string
$file The file to create a link for.
int
$line The line number to create a link for.
string
excerpt(string $file, int $line, int $context = 2): array<string>
Grabs an excerpt from a file and highlights a given line of code.
Usage:
Debugger::excerpt('/path/to/file', 100, 4);
The above would return an array of 8 items. The 4th item would be the provided line, and would be wrapped in <span class="code-highlight"></span>
. All the lines are processed with highlight_string() as well, so they have basic PHP syntax highlighting applied.
string
$file Absolute path to a PHP file.
int
$line Line number to highlight.
int
$context optional Number of lines of context to extract above and below $line.
array<string>
export(mixed $var, Cake\Error\Debug\DebugContext $context): Cake\Error\Debug\NodeInterface
Protected export function used to keep track of indentation and recursion.
mixed
$var The variable to dump.
Cake\Error\Debug\DebugContext
$context Dump context
Cake\Error\Debug\NodeInterface
exportArray(array $var, Cake\Error\Debug\DebugContext $context): Cake\Error\Debug\ArrayNode
Export an array type object. Filters out keys used in datasource configuration.
The following keys are replaced with ***'s
array
$var The array to export.
Cake\Error\Debug\DebugContext
$context The current dump context.
Cake\Error\Debug\ArrayNode
exportObject(object $var, Cake\Error\Debug\DebugContext $context): Cake\Error\Debug\NodeInterface
Handles object to node conversion.
object
$var Object to convert.
Cake\Error\Debug\DebugContext
$context The dump context.
Cake\Error\Debug\NodeInterface
exportVar(mixed $var, int $maxDepth = 3): string
Converts a variable to a string for debug output.
Note: The following keys will have their contents replaced with *****
:
This is done to protect database credentials, which could be accidentally shown in an error message if CakePHP is deployed in development mode.
mixed
$var Variable to convert.
int
$maxDepth optional The depth to output to. Defaults to 3.
string
exportVarAsNodes(mixed $var, int $maxDepth = 3): Cake\Error\Debug\NodeInterface
Convert the variable to the internal node tree.
The node tree can be manipulated and serialized more easily than many object graphs can.
mixed
$var Variable to convert.
int
$maxDepth optional The depth to generate nodes to. Defaults to 3.
Cake\Error\Debug\NodeInterface
exportVarAsPlainText(mixed $var, int $maxDepth = 3): string
Converts a variable to a plain text string.
mixed
$var Variable to convert.
int
$maxDepth optional The depth to output to. Defaults to 3.
string
formatHtmlMessage(string $message): string
Format an exception message to be HTML formatted.
Does the following formatting operations:
bool
into <code>bool</code>
<br />
string
$message The string message to format.
string
formatTrace(Throwable|array $backtrace, array<string, mixed> $options = []): array|string
Formats a stack trace based on the supplied options.
depth
- The number of stack frames to return. Defaults to 999format
- The format you want the return. Defaults to the currently selected format. If format is 'array' or 'points' the return will be an array.args
- Should arguments for functions be shown? If true, the arguments for each method call will be displayed.start
- The stack frame to start generating a trace from. Defaults to 0Throwable|array
$backtrace Trace as array or an exception object.
array<string, mixed>
$options optional Format for outputting stack trace.
array|string
getConfig(string|null $key = null, mixed $default = null): mixed
Returns the config.
Reading the whole config:
$this->getConfig();
Reading a specific value:
$this->getConfig('key');
Reading a nested value:
$this->getConfig('some.nested.key');
Reading with default value:
$this->getConfig('some-key', 'default-value');
string|null
$key optional The key to get or null for the whole config.
mixed
$default optional The return value when the key does not exist.
mixed
getConfigOrFail(string $key): mixed
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
string
$key The key to get.
mixed
InvalidArgumentException
getExportFormatter(): Cake\Error\Debug\FormatterInterface
Get the configured export formatter or infer one based on the environment.
Cake\Error\Debug\FormatterInterface
getInstance(string|null $class = null): static
Returns a reference to the Debugger singleton object instance.
string|null
$class optional Class name.
static
getOutputFormat(): string
Get the output format for Debugger error rendering.
string
getType(mixed $var): string
Get the type of the given variable. Will return the class name for objects.
mixed
$var The variable to get the type of.
string
log(mixed $var, string|int $level = 'debug', int $maxDepth = 3): void
Creates an entry in the log file. The log entry will contain a stack trace from where it was called. as well as export the variable using exportVar. By default, the log is written to the debug log.
mixed
$var Variable or content to log.
string|int
$level optional Type of log to use. Defaults to 'debug'.
int
$maxDepth optional The depth to output to. Defaults to 3.
void
outputError(array $data): void
Takes a processed array of data from an error and displays it in the chosen format.
array
$data Data to output.
void
outputMask(): array<string, string>
Reads the current output masking.
array<string, string>
printVar(mixed $var, array $location = [], bool|null $showHtml = null): void
Prints out debug information about given variable.
mixed
$var Variable to show debug information for.
array
$location optional If contains keys "file" and "line" their values will be used to show location info.
bool|null
$showHtml optional If set to true, the method prints the debug data encoded as HTML. If false, plain text formatting will be used. If null, the format will be chosen based on the configured exportFormatter, or environment conditions.
void
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this
Sets the config.
Setting a specific value:
$this->setConfig('key', $value);
Setting a nested value:
$this->setConfig('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);
array<string, mixed>|string
$key The key to set, or a complete array of configs.
mixed|null
$value optional The value to set.
bool
$merge optional Whether to recursively merge or overwrite existing config, defaults to true.
$this
Cake\Core\Exception\CakeException
setEditor(string $name): void
Choose the editor link style you want to use.
string
$name The editor name.
void
setOutputFormat(string $format): void
Set the output format for Debugger error rendering.
string
$format The format you want errors to be output as.
void
InvalidArgumentException
setOutputMask(array<string, string> $value, bool $merge = true): void
Sets configurable masking of debugger output by property name and array key names.
Debugger::setOutputMask(['password' => '[*****]');
array<string, string>
$value An array where keys are replaced by their values in output.
bool
$merge optional Whether to recursively merge or overwrite existing config, defaults to true.
void
trace(array<string, mixed> $options = []): array|string
Outputs a stack trace based on the supplied options.
depth
- The number of stack frames to return. Defaults to 999format
- The format you want the return. Defaults to the currently selected format. If format is 'array' or 'points' the return will be an array.args
- Should arguments for functions be shown? If true, the arguments for each method call will be displayed.start
- The stack frame to start generating a trace from. Defaults to 0array<string, mixed>
$options optional Format for outputting stack trace.
array|string
trimPath(string $path): string
Shortens file paths by replacing the application base path with 'APP', and the CakePHP core path with 'CORE'.
string
$path Path to shorten.
string
Runtime config
array<string, mixed>
Whether the config property has already been configured with defaults
bool
Holds current output data when outputFormat is false.
array
Default configuration
array<string, mixed>
The current output format.
string
Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
array<string, array<string, mixed>>
A map of editors to their link templates.
array<string, string|callable>
Mapping for error renderers.
Error renderers are replacing output formatting with an object based system. Having Debugger handle and render errors will be deprecated and the new ErrorTrap system should be used instead.
array<string, class-string>
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.Error.Debugger.html