Class Debugger
Provide custom logging and error handling.
Debugger overrides PHP's default error handling to provide stack traces and enhanced logging
Link: http://book.cakephp.org/2.0/en/development/debugging.html#debugger-class
Copyright: Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
License: License (http://www.opensource.org/licenses/mit-license.php)
Location: Cake/Utility/Debugger.php
Properties summary
-
$_dataprotectedstringHolds current output data when outputFormat is false. -
$_outputFormatprotectedstringThe current output format. -
$_templatesprotectedstringTemplates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
-
$errorspublicarrayA list of errors generated by the application.
Method Summary
-
__construct() public
Constructor. -
_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. -
getInstance() public static
Returns a reference to the Debugger singleton object instance. -
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.
-
output() public deprecated
Switches output format, updates format strings. Can be used to switch the active output format:
-
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. -
showError() public static deprecated
Overrides PHP's default error handling. -
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
_object() protected static ¶
_object( string $var )
Handles object to string conversion.
Parameters
- string $var
- Object to convert
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 String::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,contextandtrace. 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', array('callback' => array($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
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.
dump() public static ¶
dump( mixed $var )
Recursively formats and outputs the contents of the supplied variable.
Parameters
- mixed $var
- the variable to dump
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( string $var , integer $recursion = 0 )
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
- integer $recursion optional 0
Returns
Variable as a formatted string
Link
getInstance() public static ¶
getInstance( string $class = null )
Returns a reference to the Debugger singleton object instance.
Parameters
- string $class optional null
Returns
log() public static ¶
log( mixed $var , integer $level = LOG_DEBUG )
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 $level optional LOG_DEBUG
- type of log to use. Defaults to LOG_DEBUG
Link
output() public deprecated ¶
output( string $format = null , array $strings = array() )
Switches output format, updates format strings. Can be used to switch the active output format:
Deprecated
Use Debugger::outputAs() and Debugger::addFormat(). Will be removed in 3.0
Parameters
- string $format optional null
Format to use, including 'js' for JavaScript-enhanced HTML, 'html' for straight HTML output, or 'txt' for unformatted text.
- array $strings optional array()
- Template strings to be used for the output format.
Returns
outputAs() public static ¶
outputAs( string $format = null )
Get/Set the output format for Debugger error rendering.
Parameters
- string $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
outputError() public ¶
outputError( string $data )
Takes a processed array of data from an error and displays it in the chosen format.
Parameters
- string $data
showError() public static deprecated ¶
showError( integer $code , string $description , string $file = null , integer $line = null , array $context = null )
Overrides PHP's default error handling.
Deprecated
Parameters
- integer $code
- Code of error
- string $description
- Error description
- string $file optional null
- File on which error occurred
- integer $line optional null
- Line that triggered the error
- array $context optional null
- Context
Returns
true if error was handled
trace() public static ¶
trace( array $options = array() )
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 array()
- 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
Properties detail
$_templates ¶
Templates used when generating trace or error strings. Can be global or indexed by the format value used in $_outputFormat.
array( 'log' => array( 'trace' => '{:reference} - {:path}, line {:line}', 'error' => "{:error} ({:code}): {:description} in [{:file}, line {:line}]" ), 'js' => array( 'error' => '', 'info' => '', 'trace' => '<pre class="stack-trace">{:trace}</pre>', 'code' => '', 'context' => '', 'links' => array() ), 'html' => array( '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>' ), 'txt' => array( 'error' => "{:error}: {:code} :: {:description} on line {:line} of {:path}\n{:info}", 'code' => '', 'info' => '' ), 'base' => array( 'traceLine' => '{:reference} - {:path}, line {:line}', 'trace' => "Trace:\n{:trace}\n", 'context' => "Context:\n{:context}\n", ), 'log' => array(), )