Class Debugger

Provide custom logging and error handling.

Debugger extends PHP's default error handling and gives simpler to use more powerful interfaces.

Namespace: Cake\Error

Properties summary

$_config protected

array

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_data protected

array

Holds current output data when outputFormat is false.
$_defaultConfig protected

array

Default configuration
$_outputFormat protected

string

The current output format.
$_templates protected

array

Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
$editors protected

array

A map of editors to their link templates.

Method Summary

__construct() public

Constructor.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_highlight() protected static

Wraps the highlight_string function in case the server API does not implement the function as it is the case of the HipHop interpreter
addEditor() public static

Add an editor link format
addFormat() public static

Add an output format or update a format in Debugger.
checkSecurityKeys() public static

Verifies that the application's salt and cipher seed value has been changed from the default value.
configInstance() public static

Read or write configuration options for the Debugger instance.
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
dump() public static

Recursively formats and outputs the contents of the supplied variable.
editorUrl() public static

Get a formatted URL for the active editor.
excerpt() public static

Grabs an excerpt from a file and highlights a given line of code.
export() protected static

Protected export function used to keep track of indentation and recursion.
exportArray() protected static

Export an array type object. Filters out keys used in datasource configuration.
exportObject() protected static

Handles object to node conversion.
exportVar() public static

Converts a variable to a string for debug output.
formatHtmlMessage() public static

Format an exception message to be HTML formatted.
formatTrace() public static

Formats a stack trace based on the supplied options.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getExportFormatter() public

Get the configured export formatter or infer one based on the environment.
getInstance() public static

Returns a reference to the Debugger singleton object instance.
getOutputFormat() public static

Get the output format for Debugger error rendering.
getType() public static

Get the type of the given variable. Will return the class name for objects.
log() public static

Creates an entry in the log file. The log entry will contain a stack trace from where it was called.
outputError() public

Takes a processed array of data from an error and displays it in the chosen format.
outputMask() public static

Reads the current output masking.
printVar() public static

Prints out debug information about given variable.
setConfig() public

Sets the config.
setEditor() public static

Choose the editor link style you want to use.
setOutputFormat() public static

Set the output format for Debugger error rendering.
setOutputMask() public static

Sets configurable masking of debugger output by property name and array key names.
trace() public static

Outputs a stack trace based on the supplied options.
trimPath() public static

Shortens file paths by replacing the application base path with 'APP', and the CakePHP core path with 'CORE'.

Method Detail

__construct() public

__construct()

Constructor.

_configDelete() protected

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key: Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() protected

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key: Key to write to.
mixed $value: Value to write.
bool|string $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_highlight() protected static

_highlight(string $str)

Wraps the highlight_string function in case the server API does not implement the function as it is the case of the HipHop interpreter

Parameters

string $str: The string to convert.

Returns

string

addEditor() public static

addEditor(string $name, mixed $template)

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.

Parameters

string $name: The name of the editor.
string|\Closure $template: The string template or closure

addFormat() public static

addFormat(string $format, array $strings)

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:

'error' - Used for the container for the error message. Gets the following template variables: id, error, code, description, path, line, links, info
'info' - A combination of code, context and trace. Will be set with the contents of the other template keys.
'trace' - The container for a stack trace. Gets the following template variables: trace
'context' - The container element for the context variables. Gets the following templates: id, context
'links' - An array of HTML links that are used for creating links to other resources. Typically this is used to create javascript links to open other sections. Link keys, are: code, context, help. See the JS output format for an example.
'traceLine' - Used for creating lines in the stacktrace. Gets the following template variables: 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.

Parameters

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.

Returns

array

The resulting format string set.

checkSecurityKeys() public static

checkSecurityKeys()

Verifies that the application's salt and cipher seed value has been changed from the default value.

configInstance() public static

configInstance(mixed $key, mixed $value, bool $merge)

Read or write configuration options for the Debugger instance.

Parameters

string|array|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.

Returns

mixed

Config value being read, or the object itself on write operations.

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

configShallow() public

configShallow(mixed $key, mixed $value)

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']);

Parameters

string|array $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

dump() public static

dump(mixed $var, int $maxDepth)

Recursively formats and outputs the contents of the supplied variable.

Parameters

mixed $var: The variable to dump.
int $maxDepth optional: The depth to output to. Defaults to 3.

Links

https://book.cakephp.org/4/en/development/debugging.html#outputting-values

editorUrl() public static

editorUrl(string $file, int $line)

Get a formatted URL for the active editor.

Parameters

string $file: The file to create a link for.
int $line: The line number to create a link for.

Returns

string

The formatted URL.

excerpt() public static

excerpt(string $file, int $line, int $context)

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 of the lines are processed with highlight_string() as well, so they have basic PHP syntax highlighting applied.

Parameters

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.

Returns

array

Set of lines highlighted

Links

https://book.cakephp.org/4/en/development/debugging.html#getting-an-excerpt-from-a-file

export() protected static

export(mixed $var, \Cake\Error\Debug\DebugContext $context)

Protected export function used to keep track of indentation and recursion.

Parameters

mixed $var: The variable to dump.
\Cake\Error\Debug\DebugContext $context: Dump context

Returns

\Cake\Error\Debug\NodeInterface

The dumped variable.

exportArray() protected static

exportArray(array $var, \Cake\Error\Debug\DebugContext $context)

Export an array type object. Filters out keys used in datasource configuration.

The following keys are replaced with ***'s

password
login
host
database
port
prefix
schema

Parameters

array $var: The array to export.
\Cake\Error\Debug\DebugContext $context: The current dump context.

Returns

\Cake\Error\Debug\ArrayNode

Exported array.

exportObject() protected static

exportObject(object $var, \Cake\Error\Debug\DebugContext $context)

Handles object to node conversion.

Parameters

object $var: Object to convert.
\Cake\Error\Debug\DebugContext $context: The dump context.

Returns

\Cake\Error\Debug\NodeInterface

exportVar() public static

exportVar(mixed $var, int $maxDepth)

Converts a variable to a string for debug output.

Note: The following keys will have their contents replaced with *****:

password
login
host
database
port
prefix
schema

This is done to protect database credentials, which could be accidentally shown in an error message if CakePHP is deployed in development mode.

Parameters

mixed $var: Variable to convert.
int $maxDepth optional: The depth to output to. Defaults to 3.

Returns

string

Variable as a formatted string

formatHtmlMessage() public static

formatHtmlMessage(string $message)

Format an exception message to be HTML formatted.

Does the following formatting operations:

HTML escape the message.
Convert bool into <code>bool</code>
Convert newlines into <br />

Parameters

string $message: The string message to format.

Returns

string

Formatted message.

formatTrace() public static

formatTrace(mixed $backtrace, array $options)

Formats a stack trace based on the supplied options.

Options

depth - The number of stack frames to return. Defaults to 999
format - 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 0

Parameters

array|\Throwable $backtrace: Trace as array or an exception object.
array $options optional: Format for outputting stack trace.

Returns

string|array

Formatted stack trace.

Links

https://book.cakephp.org/4/en/development/debugging.html#generating-stack-traces

getConfig() public

getConfig(?string $key, mixed $default)

Returns the config.

Usage

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');

Parameters

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.

Returns

mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public

getConfigOrFail(string $key)

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getExportFormatter() public

getExportFormatter()

Get the configured export formatter or infer one based on the environment.

Returns

\Cake\Error\Debug\FormatterInterface

getInstance() public static

getInstance(?string $class)

Returns a reference to the Debugger singleton object instance.

Parameters

string|null $class optional: Class name.

Returns

static

getOutputFormat() public static

getOutputFormat()

Get the output format for Debugger error rendering.

Returns

string

Returns the current format when getting.

getType() public static

getType(mixed $var)

Get the type of the given variable. Will return the class name for objects.

Parameters

mixed $var: The variable to get the type of.

Returns

string

The type of variable.

log() public static

log(mixed $var, mixed $level, int $maxDepth)

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.

Parameters

mixed $var: Variable or content to log.
int|string $level optional: Type of log to use. Defaults to 'debug'.
int $maxDepth optional: The depth to output to. Defaults to 3.

outputError() public

outputError(array $data)

Takes a processed array of data from an error and displays it in the chosen format.

Parameters

array $data: Data to output.

outputMask() public static

outputMask()

Reads the current output masking.

Returns

array

printVar() public static

printVar(mixed $var, array $location, ?bool $showHtml)

Prints out debug information about given variable.

Parameters

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.

setConfig() public

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

Usage

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']);

Parameters

string|array $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.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

setEditor() public static

setEditor(string $name)

Choose the editor link style you want to use.

Parameters

string $name: The editor name.

setOutputFormat() public static

setOutputFormat(string $format)

Set the output format for Debugger error rendering.

Parameters

string $format: The format you want errors to be output as.

Throws

InvalidArgumentException
When choosing a format that doesn't exist.

setOutputMask() public static

setOutputMask(array $value, bool $merge)

Sets configurable masking of debugger output by property name and array key names.

Example

Debugger::setOutputMask(['password' => '[*****]');

Parameters

array $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.

trace() public static

trace(array $options)

Outputs a stack trace based on the supplied options.

Options

depth - The number of stack frames to return. Defaults to 999
format - 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 0

Parameters

array $options optional: Format for outputting stack trace.

Returns

string|array

Formatted stack trace.

Links

https://book.cakephp.org/4/en/development/debugging.html#generating-stack-traces

trimPath() public static

trimPath(string $path)

Shortens file paths by replacing the application base path with 'APP', and the CakePHP core path with 'CORE'.

Parameters

string $path: Path to shorten.

Returns

string

Normalized path

Property Detail

`$_config` protected

Runtime config

Type

array

`$_configInitialized` protected

Whether the config property has already been configured with defaults

Type

bool

`$_data` protected

Holds current output data when outputFormat is false.

Type

array

`$_defaultConfig` protected

Default configuration

Type

array

`$_outputFormat` protected

The current output format.

Type

string

`$_templates` protected

Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.

Type

array

`$editors` protected

A map of editors to their link templates.

Type

array

© 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.1/class-Cake.Error.Debugger.html

Class Debugger

Properties summary

Method Summary

Method Detail

__construct() public

_configDelete() protected

Parameters

Throws

_configRead() protected

Parameters

Returns

_configWrite() protected

Parameters

Throws

_highlight() protected static

Parameters

Returns

addEditor() public static

Parameters

addFormat() public static

Parameters

Returns

checkSecurityKeys() public static

configInstance() public static

Parameters

Returns

Throws

configShallow() public

Parameters

Returns

dump() public static

Parameters

See Also

Links

editorUrl() public static

Parameters

Returns

excerpt() public static

Parameters

Returns

See Also

Links

export() protected static

Parameters

Returns

exportArray() protected static

Parameters

Returns

exportObject() protected static

Parameters

Returns

See Also

exportVar() public static

Parameters

Returns

formatHtmlMessage() public static

Parameters

Returns

formatTrace() public static

Options

Parameters

Returns

Links

getConfig() public

Usage

Parameters

Returns

getConfigOrFail() public

Parameters

Returns

Throws

getExportFormatter() public

Returns

getInstance() public static

Parameters

Returns

getOutputFormat() public static

Returns

getType() public static

Parameters

`$_config` protected

`$_configInitialized` protected

`$_data` protected

`$_defaultConfig` protected

`$_outputFormat` protected

`$_templates` protected

`$editors` protected