Class Debugger
Provide custom logging and error handling.
Debugger overrides PHP's default error handling to provide stack traces and enhanced logging
- Cake\Error\Debugger uses Cake\Core\InstanceConfigTrait
Link: https://book.cakephp.org/3.0/en/development/debugging.html#namespace-Cake\Error
Location: Error/Debugger.php
Properties summary
-
$_data
protectedarray
Holds current output data when outputFormat is false. -
$_defaultConfig
protectedarray
Default configuration -
$_outputFormat
protectedstring
The current output format. -
$_templates
protectedarray
Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
-
$errors
publicarray
A list of errors generated by the application.
Inherited Properties
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. -
configInstance() public static
Read or write configuration options for the Debugger instance. -
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. -
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. 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. -
outputMask() public static
Reads the current output masking. -
printVar() public static
Prints out debug information about given variable. -
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
_array() protected static ¶
_array( array $var , integer $depth , integer $indent )
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.
- integer $depth
- The current depth, used for recursion tracking.
- integer $indent
- The current indentation level.
Returns
Exported array.
_export() protected static ¶
_export( mixed $var , integer $depth , integer $indent )
Protected export function used to keep track of indentation and recursion.
Parameters
- mixed $var
- The variable to dump.
- integer $depth
- The remaining depth.
- integer $indent
- The current indentation level.
Returns
The dumped variable.
_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
_object() protected static ¶
_object( object $var , integer $depth , integer $indent )
Handles object to string conversion.
Parameters
- object $var
- Object to convert.
- integer $depth
- The current depth, used for tracking recursion.
- integer $indent
- The current indentation level.
Returns
See
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
andtrace
. 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
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( string|array|null $key null , mixed|null $value null , boolean $merge true )
Read or write configuration options for the Debugger instance.
Parameters
- string|array|null $key optional null
- The key to get/set, or a complete array of configs.
- mixed|null $value optional null
- The value to set.
- boolean $merge optional true
- Whether to recursively merge or overwrite existing config, defaults to true.
Returns
Config value being read, or the object itself on write operations.
Throws
dump() public static ¶
dump( mixed $var , integer $depth 3 )
Recursively formats and outputs the contents of the supplied variable.
Parameters
- mixed $var
- The variable to dump.
- integer $depth optional 3
- The depth to output to. Defaults to 3.
See
Link
excerpt() public static ¶
excerpt( string $file , integer $line , integer $context 2 )
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.
- integer $line
- Line number to highlight.
- integer $context optional 2
- Number of lines of context to extract above and below $line.
Returns
Set of lines highlighted
See
Link
exportVar() public static ¶
exportVar( mixed $var , integer $depth 3 )
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.
- integer $depth optional 3
- The depth to output to. Defaults to 3.
Returns
Variable as a formatted string
formatTrace() public static ¶
formatTrace( array|Exception $backtrace , array $options [] )
Formats a stack trace based on the supplied options.
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 0
Parameters
- array|Exception $backtrace
- Trace as array or an exception object.
- array $options optional []
- Format for outputting stack trace.
Returns
Formatted stack trace.
Link
getInstance() public static ¶
getInstance( string|null $class null )
Returns a reference to the Debugger singleton object instance.
Parameters
- string|null $class optional null
- Class name.
Returns
getOutputFormat() public static ¶
getOutputFormat( )
Get the output format for Debugger error rendering.
Returns
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
The type of variable.
log() public static ¶
log( mixed $var , integer|string $level 'debug' , integer $depth 3 )
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.
- integer|string $level optional 'debug'
- Type of log to use. Defaults to 'debug'.
- integer $depth optional 3
- The depth to output to. Defaults to 3.
outputAs() public static ¶
outputAs( string|null $format null )
Get/Set the output format for Debugger error rendering.
Deprecated
Parameters
- string|null $format optional null
The format you want errors to be output as. Leave null to get the current format.
Returns
Returns null when setting. Returns the current format when getting.
Throws
When choosing a format that doesn't exist.
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.
printVar() public static ¶
printVar( mixed $var , array $location [] , boolean|null $showHtml null )
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.
- boolean|null $showHtml optional null
If set to true, the method prints the debug data in a browser-friendly way.
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
When choosing a format that doesn't exist.
setOutputMask() public static ¶
setOutputMask( array $value , boolean $merge true )
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.
- boolean $merge optional true
- 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 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 0
Parameters
- array $options optional []
- Format for outputting stack trace.
Returns
Formatted stack trace.
Link
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
Normalized path
Methods used from Cake\Core\InstanceConfigTrait
_configDelete() protected ¶
_configDelete( string $key )
Deletes a single config key.
Parameters
- string $key
- Key to delete.
Throws
_configRead() protected ¶
_configRead( string|null $key )
Reads a config key.
Parameters
- string|null $key
- Key to read.
Returns
_configWrite() protected ¶
_configWrite( string|array $key , mixed $value , boolean|string $merge false )
Writes a config key.
Parameters
- string|array $key
- Key to write to.
- mixed $value
- Value to write.
- boolean|string $merge optional false
True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Throws
config() public ¶
config( string|array|null $key null , mixed|null $value null , boolean $merge true )
Gets/Sets the config.
Usage
Reading the whole config:
$this->config();
Reading a specific value:
$this->config('key');
Reading a nested value:
$this->config('some.nested.key');
Setting a specific value:
$this->config('key', $value);
Setting a nested value:
$this->config('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->config(['one' => 'value', 'another' => 'value']);
Deprecated
Parameters
- string|array|null $key optional null
- The key to get/set, or a complete array of configs.
- mixed|null $value optional null
- The value to set.
- boolean $merge optional true
- Whether to recursively merge or overwrite existing config, defaults to true.
Returns
Config value being read, or the object itself on write operations.
Throws
configShallow() public ¶
configShallow( string|array $key , mixed|null $value null )
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 null
- The value to set.
Returns
$this
getConfig() public ¶
getConfig( string|null $key null , mixed $default null )
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 null
- The key to get or null for the whole config.
- mixed $default optional null
- The return value when the key does not exist.
Returns
Config value being read.
setConfig() public ¶
setConfig( string|array $key , mixed|null $value null , boolean $merge true )
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 null
- The value to set.
- boolean $merge optional true
- Whether to recursively merge or overwrite existing config, defaults to true.
Returns
$this
Throws
Properties detail
$_templates ¶
Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
[ 'log' => [ 'trace' => '{:reference} - {:path}, line {:line}', 'error' => '{:error} ({:code}): {:description} in [{:file}, line {:line}]' ], 'js' => [ 'error' => '', 'info' => '', 'trace' => '<pre class="stack-trace">{:trace}</pre>', 'code' => '', 'context' => '', 'links' => [], 'escapeContext' => true, ], 'html' => [ 'trace' => '<pre class="cake-error trace"><b>Trace</b> <p>{:trace}</p></pre>', 'context' => '<pre class="cake-error context"><b>Context</b> <p>{:context}</p></pre>', 'escapeContext' => true, ], 'txt' => [ 'error' => "{:error}: {:code} :: {:description} on line {:line} of {:path}\n{:info}", 'code' => '', 'info' => '' ], 'base' => [ 'traceLine' => '{:reference} - {:path}, line {:line}', 'trace' => "Trace:\n{:trace}\n", 'context' => "Context:\n{:context}\n", ] ]