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

Properties summary

  • $_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.

  • $errors public
    array
    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 deprecated
    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

__construct()source public

__construct( )

Constructor.

_array()source 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

string
Exported array.

_export()source 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

string
The dumped variable.

_highlight()source 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

_object()source 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

string

See

\Cake\Error\Debugger::exportVar()

addFormat()source 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()source public static

checkSecurityKeys( )

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

configInstance()source 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

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.

dump()source 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

\Cake\Error\Debugger::exportVar()

Link

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

excerpt()source 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

array
Set of lines highlighted

See

https://secure.php.net/highlight_string

Link

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

exportVar()source 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

string
Variable as a formatted string

formatTrace()source 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 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|Exception $backtrace
Trace as array or an exception object.
array $options optional []
Format for outputting stack trace.

Returns

mixed
Formatted stack trace.

Link

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

getInstance()source 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

Cake\Error\Debugger

getOutputFormat()source public static

getOutputFormat( )

Get the output format for Debugger error rendering.

Returns

string
Returns the current format when getting.

getType()source 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()source 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()source public static deprecated

outputAs( string|null $format = null )

Get/Set the output format for Debugger error rendering.

Deprecated

3.5.0 Use getOutputFormat()/setOutputFormat() instead.

Parameters

string|null $format optional null

The format you want errors to be output as. Leave null to get the current format.

Returns

string|null
Returns null when setting. Returns the current format when getting.

Throws

InvalidArgumentException
When choosing a format that doesn't exist.

outputError()source 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()source public static

outputMask( )

Reads the current output masking.

Returns

array

printVar()source 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()source 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()source 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()source 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

mixed
Formatted stack trace.

Link

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

trimPath()source 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

Methods used from Cake\Core\InstanceConfigTrait

_configDelete()source 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()source protected

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key
Key to read.

Returns

mixed

_configWrite()source 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

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

config()source public deprecated

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

3.4.0 use setConfig()/getConfig() instead.

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

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()source 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()source 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

mixed
Config value being read.

setConfig()source 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

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

Properties detail

$_datasource

protected array

Holds current output data when outputFormat is false.

[]

$_defaultConfigsource

protected array

Default configuration

[
    'outputMask' => []
]

$_outputFormatsource

protected string

The current output format.

'js'

$_templatessource

protected array

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",
    ]
]

$errorssource

public array

A list of errors generated by the application.

[]

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