Debugging

Debugging is an inevitable and necessary part of any development cycle. While CakePHP doesn't offer any tools that directly connect with any IDE or editor, CakePHP does provide several tools to assist in debugging and exposing what is running under the hood of your application.

Basic Debugging

noindex

The debug() function is a globally available function that works similarly to the PHP function print_r(). The debug() function allows you to show the contents of a variable in a number of different ways. First, if you'd like data to be shown in an HTML-friendly way, set the second parameter to true. The function also prints out the line and file it is originating from by default.

Output from this function is only shown if the core $debug variable has been set to true.

Also see dd(), pr() and pj().

The stackTrace() function is available globally, and allows you to output a stack trace wherever the function is called.

If you have Psysh installed you can use this function in CLI environments to open an interactive console with the current local scope:

// Some code
eval(breakpoint());

Will open an interactive console that can be used to check local variables and execute other code. You can exit the interactive debugger and resume the original execution by running quit or q in the interactive session.

Using the Debugger Class

class Cake\Error\Debugger

To use the debugger, first ensure that Configure::read('debug') is set to true. You can use filter_var(env('DEBUG', true), FILTER_VALIDATE_BOOLEAN), in config/app.php file to ensure that debug is a boolean.

The following configuration options can be set in config/app.php to change how Debugger behaves:

• Debugger.editor Choose the which editor URL format you want to use. By default atom, emacs, macvim, phpstorm, sublime, textmate, and vscode are available. You can add additional editor link formats using Debugger::addEditor() during your application bootstrap.
• Debugger.outputMask A mapping of key to replacement values that Debugger should replace in dumped data and logs generated by Debugger.

Outputting Values

Dump prints out the contents of a variable. It will print out all properties and methods (if any) of the supplied variable:

$foo = [1,2,3];

Debugger::dump($foo);

// Outputs
array(
    1,
    2,
    3
)

// Simple object
$car = new Car();

Debugger::dump($car);

// Outputs
object(Car) {
    color => 'red'
    make => 'Toyota'
    model => 'Camry'
    mileage => (int)15000
}

Masking Data

When dumping data with Debugger or rendering error pages, you may want to hide sensitive keys like passwords or API keys. In your config/bootstrap.php you can mask specific keys:

Debugger::setOutputMask([
    'password' => 'xxxxx',
    'awsKey' => 'yyyyy',
]);

As of 4.1.0 you can use the Debugger.outputMask configuration value to set output masks.

Logging With Stack Traces

Creates a detailed stack trace log at the time of invocation. The log() method prints out data similar to that done by Debugger::dump(), but to the debug.log instead of the output buffer. Note your tmp directory (and its contents) must be writable by the web server for log() to work correctly.

Generating Stack Traces

Returns the current stack trace. Each line of the trace includes the calling method, including which file and line the call originated from:

// In PostsController::index()
pr(Debugger::trace());

// Outputs
PostsController::index() - APP/Controller/DownloadsController.php, line 48
Dispatcher::_invoke() - CORE/src/Routing/Dispatcher.php, line 265
Dispatcher::dispatch() - CORE/src/Routing/Dispatcher.php, line 237
[main] - APP/webroot/index.php, line 84

Above is the stack trace generated by calling Debugger::trace() in a controller action. Reading the stack trace bottom to top shows the order of currently running functions (stack frames).

Getting an Excerpt From a File

Grab an excerpt from the file at $path (which is an absolute filepath), highlights line number $line with $context number of lines around it. :

pr(Debugger::excerpt(ROOT . DS . LIBS . 'debugger.php', 321, 2));

// Will output the following.
Array
(
    [0] => <code><span style="color: #000000"> * @access public</span></code>
    [1] => <code><span style="color: #000000"> */</span></code>
    [2] => <code><span style="color: #000000">    function excerpt($file, $line, $context = 2) {</span></code>

    [3] => <span class="code-highlight"><code><span style="color: #000000">        $data = $lines = array();</span></code></span>
    [4] => <code><span style="color: #000000">        $data = @explode("\n", file_get_contents($file));</span></code>
)

Although this method is used internally, it can be handy if you're creating your own error messages or log entries for custom situations.

Get the type of a variable. Objects will return their class name

Editor Integration

Exception and error pages can contain URLs that directly open in your editor or IDE. CakePHP ships with URL formats for several popular editors, and you can add additional editor formats if required during application bootstrap:

// Generate links for vscode.
Debugger::setEditor('vscode')

// Add a custom format
// Format strings will have the {file} and {line}
// placeholders replaced.
Debugger::addEditor('custom', 'thing://open={file}&line={line}');

// You can also use a closure to generate URLs
Debugger::addEditor('custom', function ($file, $line) {
    return "thing://open={$file}&line={$line}";
});

Using Logging to Debug

Logging messages is another good way to debug applications, and you can use Cake\Log\Log to do logging in your application. All objects that use LogTrait have an instance method log() which can be used to log messages:

$this->log('Got here', 'debug');

The above would write Got here into the debug log. You can use log entries to help debug methods that involve redirects or complicated loops. You can also use Cake\Log\Log::write() to write log messages. This method can be called statically anywhere in your application one Log has been loaded:

// At the top of the file you want to log in.
use Cake\Log\Log;

// Anywhere that Log has been imported.
Log::debug('Got here');

Debug Kit

DebugKit is a plugin that provides a number of good debugging tools. It primarily provides a toolbar in the rendered HTML, that provides a plethora of information about your application and the current request. See the DebugKit Documentation for how to install and use DebugKit.