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

debug(mixed $var, boolean $showHtml = null, $showFrom = true)

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.

New in version 3.3.0: Calling this method will return passed $var, so that you can, for instance, place it in return statements, for example:

return debug($data); // will return $data in any case.

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

stackTrace()

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

breakpoint()

New in version 3.1.

If you have Psysh installed you can use this function in CLI enviroments 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.

Outputting Values

static Cake\Error\Debugger::dump($var, $depth = 3)

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',
]);

New in version 3.4.0: Output masking was added in 3.4.0

Logging With Stack Traces

static Cake\Error\Debugger::log($var, $level = 7, $depth = 3)

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

static Cake\Error\Debugger::trace($options)

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

static Cake\Error\Debugger::excerpt($file, $line, $context)

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.

static Cake\Error\Debugger::getType($var)

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

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 CakeLog 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 Debug Kit chapter for how to install and use DebugKit.