Class Debugger

Provide custom logging and error handling.

Debugger overrides PHP's default error handling to provide stack traces and enhanced logging

Namespace: Cake\Error
Link: http://book.cakephp.org/3.0/en/development/debugging.html#namespace-Cake\Error

Property Summary

$_data protected

string

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

string

The current output format.
$_templates protected

string

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

array

A list of errors generated by the application.

Method Summary

__construct() public

Constructor.
_array() protected static

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

Protected export function used to keep track of indentation and recursion.
_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
_object() protected static

Handles object to string conversion.
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.
dump() public static

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

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

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

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

Returns a reference to the Debugger singleton object instance.
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. as well as export the variable using exportVar. By default the log is written to the debug log.
outputAs() public static

Get/Set the output format for Debugger error rendering.
outputError() public

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

Prints out debug information about given variable.
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.

_array() ¶ protected static

_array(array $var, int $depth, int $indent): string

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.
int $depth: The current depth, used for recursion tracking.
int $indent: The current indentation level.

Returns

string

_export() ¶ protected static

_export(mixed $var, int $depth, int $indent): string

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

Parameters

mixed $var: The variable to dump.
int $depth: The remaining depth.
int $indent: The current indentation level.

Returns

string

_highlight() ¶ protected static

_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

Parameters

string $str: The string to convert.

Returns

string

_object() ¶ protected static

_object(string $var, int $depth, int $indent): string

Handles object to string conversion.

Parameters

string $var: Object to convert.
int $depth: The current depth, used for tracking recursion.
int $indent: The current indentation level.

Returns

string

addFormat() ¶ public static

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:

'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

checkSecurityKeys() ¶ public static

checkSecurityKeys(): void

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

Returns

void

dump() ¶ public static

dump(mixed $var, int $depth = 3): void

Recursively formats and outputs the contents of the supplied variable.

Parameters

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

Returns

void

Links

http://book.cakephp.org/3.0/en/development/debugging.html#outputting-values

excerpt() ¶ public static

excerpt(string $file, int $line, int $context = 2): array

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

Links

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

exportVar() ¶ public static

exportVar(string $var, int $depth = 3): string

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

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

Returns

string

formatTrace() ¶ public static

formatTrace(arrayException $backtrace, array $options = []): mixed

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

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

Returns

mixed

Links

http://book.cakephp.org/3.0/en/development/debugging.html#generating-stack-traces

getInstance() ¶ public static

getInstance(string|null $class = null): object

Returns a reference to the Debugger singleton object instance.

Parameters

string|null $class optional: Class name.

Returns

object

getType() ¶ public static

getType(mixed $var): string

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

log() ¶ public static

log(mixed $var, int|string $level = 'debug', int $depth = 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.

Parameters

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

Returns

void

outputAs() ¶ public static

outputAs(string|null $format = null): string|null

Get/Set the output format for Debugger error rendering.

Parameters

string|null $format optional: The format you want errors to be output as. Leave null to get the current format.

Returns

string|null

Throws

InvalidArgumentException
When choosing a format that doesn't exist.

outputError() ¶ public

outputError(string $data): void

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

Parameters

string $data: Data to output.

Returns

void

printVar() ¶ public static

printVar(mixed $var, array $location = [], bool|null $showHtml = null): void

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 in a browser-friendly way.

Returns

void

trace() ¶ public static

trace(array $options = []): mixed

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

mixed

Links

http://book.cakephp.org/3.0/en/development/debugging.html#generating-stack-traces

trimPath() ¶ public static

trimPath(string $path): string

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

Property Detail

`$_data` ¶ protected

Holds current output data when outputFormat is false.

Type

string

`$_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

string

`$errors` ¶ public

A list of errors generated by the application.

Type

array

Namespaces

Class Debugger

Property Summary

Method Summary

__construct() public

_array() protected static

_export() protected static

_highlight() protected static

_object() protected static

addFormat() public static

checkSecurityKeys() public static

dump() public static

excerpt() public static

exportVar() public static

formatTrace() public static

getInstance() public static

getType() public static

log() public static

outputAs() public static

outputError() public

printVar() public static

trace() public static

trimPath() public static

Method Detail

__construct() ¶ public

_array() ¶ protected static

Parameters

Returns

_export() ¶ protected static

Parameters

Returns

_highlight() ¶ protected static

Parameters

Returns

_object() ¶ protected static

Parameters

Returns

See Also

addFormat() ¶ public static

Parameters

Returns

checkSecurityKeys() ¶ public static

Returns

dump() ¶ public static

Parameters

Returns

See Also

Links

excerpt() ¶ public static

Parameters

Returns

See Also

Links

exportVar() ¶ public static

Parameters

Returns

formatTrace() ¶ public static

Options

Parameters

Returns

Links

getInstance() ¶ public static

Parameters

Returns

getType() ¶ public static

Parameters

Returns

log() ¶ public static

Parameters

Returns

outputAs() ¶ public static

Parameters

Returns

Throws

outputError() ¶ public

Parameters

Returns

printVar() ¶ public static

Parameters

Returns

`$_data` ¶ protected

`$_outputFormat` ¶ protected

`$_templates` ¶ protected

`$errors` ¶ public