Docs4dev
Docs
cakephp / 4.4 / class-cake.error.debugger.html

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
Link: https://book.cakephp.org/4/en/development/debugging.html#namespace-Cake\Error

Property Summary

  • $_config protected
    array<string, mixed>

    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<string, mixed>

    Default configuration

  • $_outputFormat protected
    string

    The current output format.

  • $_templates protected
    array<string, array<string, mixed>>

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

  • $editors protected
    array<string, string|callable>

    A map of editors to their link templates.

  • $renderers protected
    array<string, class-string>

    Mapping for error renderers.

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 deprecated

    Add an output format or update a format in Debugger.

  • addRenderer() public static deprecated

    Add a renderer to the current instance.

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

  • exportVarAsNodes() public static

    Convert the variable to the internal node tree.

  • exportVarAsPlainText() public static

    Converts a variable to a plain text string.

  • 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 deprecated

    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.

  • outputError() public deprecated

    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 deprecated

    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): void

Deletes a single config key.

Parameters

string $key

Key to delete.

Returns

void

Throws

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

_configRead() protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key

Key to write to.

mixed $value

Value to write.

string|bool $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

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

_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

addEditor() public static

addEditor(string $name, Closure|string $template): void

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.

Closure|string $template

The string template or closure

Returns

void

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

addRenderer() public static

addRenderer(string $name, class-stringCake\Error\ErrorRendererInterface> $class): void

Add a renderer to the current instance.

Parameters

string $name

The alias for the the renderer.

class-stringCake\Error\ErrorRendererInterface> $class

The classname of the renderer to use.

Returns

void

checkSecurityKeys() public static

checkSecurityKeys(): void

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

Returns

void

configInstance() public static

configInstance(array<string, mixed>|string|null $key = null, mixed|null $value = null, bool $merge = true): mixed

Read or write configuration options for the Debugger instance.

Parameters

array<string, mixed>|string|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

Throws

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

configShallow() public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

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

array<string, mixed>|string $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 = 3): void

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.

Returns

void

See Also

\Cake\Error\Debugger::exportVar()

Links

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

editorUrl() public static

editorUrl(string $file, int $line): string

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

excerpt() public static

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

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

See Also

https://secure.php.net/highlight_string

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): Cake\Error\Debug\NodeInterface

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

exportArray() protected static

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

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

exportObject() protected static

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

Handles object to node conversion.

Parameters

object $var

Object to convert.

Cake\Error\Debug\DebugContext $context

The dump context.

Returns

Cake\Error\Debug\NodeInterface

See Also

\Cake\Error\Debugger::exportVar()

exportVar() public static

exportVar(mixed $var, int $maxDepth = 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

mixed $var

Variable to convert.

int $maxDepth optional

The depth to output to. Defaults to 3.

Returns

string

exportVarAsNodes() public static

exportVarAsNodes(mixed $var, int $maxDepth = 3): Cake\Error\Debug\NodeInterface

Convert the variable to the internal node tree.

The node tree can be manipulated and serialized more easily than many object graphs can.

Parameters

mixed $var

Variable to convert.

int $maxDepth optional

The depth to generate nodes to. Defaults to 3.

Returns

Cake\Error\Debug\NodeInterface

exportVarAsPlainText() public static

exportVarAsPlainText(mixed $var, int $maxDepth = 3): string

Converts a variable to a plain text string.

Parameters

mixed $var

Variable to convert.

int $maxDepth optional

The depth to output to. Defaults to 3.

Returns

string

formatHtmlMessage() public static

formatHtmlMessage(string $message): string

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

formatTrace() public static

formatTrace(Throwable|array $backtrace, array<string, mixed> $options = []): array|string

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

Throwable|array $backtrace

Trace as array or an exception object.

array<string, mixed> $options optional

Format for outputting stack trace.

Returns

array|string

Links

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

getConfig() public

getConfig(string|null $key = null, mixed $default = null): mixed

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

getConfigOrFail() public

getConfigOrFail(string $key): mixed

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

Throws

InvalidArgumentException

getExportFormatter() public

getExportFormatter(): Cake\Error\Debug\FormatterInterface

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

Returns

Cake\Error\Debug\FormatterInterface

getInstance() public static

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

Returns a reference to the Debugger singleton object instance.

Parameters

string|null $class optional

Class name.

Returns

static

getOutputFormat() public static

getOutputFormat(): string

Get the output format for Debugger error rendering.

Returns

string

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, string|int $level = 'debug', int $maxDepth = 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.

string|int $level optional

Type of log to use. Defaults to 'debug'.

int $maxDepth optional

The depth to output to. Defaults to 3.

Returns

void

outputError() public

outputError(array $data): void

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

Parameters

array $data

Data to output.

Returns

void

outputMask() public static

outputMask(): array<string, string>

Reads the current output masking.

Returns

array<string, string>

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

Returns

void

setConfig() public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

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

array<string, mixed>|string $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\CakeException
When trying to set a key that is invalid.

setEditor() public static

setEditor(string $name): void

Choose the editor link style you want to use.

Parameters

string $name

The editor name.

Returns

void

setOutputFormat() public static

setOutputFormat(string $format): void

Set the output format for Debugger error rendering.

Parameters

string $format

The format you want errors to be output as.

Returns

void

Throws

InvalidArgumentException
When choosing a format that doesn't exist.

setOutputMask() public static

setOutputMask(array<string, string> $value, bool $merge = true): void

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

Example

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

Parameters

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

Returns

void

trace() public static

trace(array<string, mixed> $options = []): array|string

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<string, mixed> $options optional

Format for outputting stack trace.

Returns

array|string

Links

https://book.cakephp.org/4/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

$_config protected

Runtime config

Type

array<string, mixed>

$_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<string, mixed>

$_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<string, array<string, mixed>>

$editors protected

A map of editors to their link templates.

Type

array<string, string|callable>

$renderers protected

Mapping for error renderers.

Error renderers are replacing output formatting with an object based system. Having Debugger handle and render errors will be deprecated and the new ErrorTrap system should be used instead.

Type

array<string, class-string>

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