Debugging

Debugging is an inevitable and necessary part of any developmentcycle. While CakePHP doesn’t offer any tools that directly connectwith any IDE or editor, CakePHP does provide several tools toassist in debugging and exposing what is running under the hood ofyour application.

Basic Debugging

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

The debug() function is a globally available function that workssimilarly to the PHP function print_r(). The debug() functionallows you to show the contents of a variable in a number ofdifferent ways. First, if you’d like data to be shown in anHTML-friendly way, set the second parameter to true. The functionalso prints out the line and file it is originating from bydefault.

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

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

  • stackTrace()

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

  • breakpoint()

If you have Psysh installed you can use thisfunction in CLI enviroments to open an interactive console with the currentlocal scope:

  1. // Some code
  2. eval(breakpoint());

Will open an interactive console that can be used to check local variablesand execute other code. You can exit the interactive debugger and resume theoriginal 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') isset 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.

Outputting Values

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

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

  1. $foo = [1,2,3];
  2.  
  3. Debugger::dump($foo);
  4.  
  5. // Outputs
  6. array(
  7.     1,
  8.     2,
  9.     3
  10. )
  11.  
  12. // Simple object
  13. $car = new Car();
  14.  
  15. Debugger::dump($car);
  16.  
  17. // Outputs
  18. object(Car) {
  19.     color => 'red'
  20.     make => 'Toyota'
  21.     model => 'Camry'
  22.     mileage => (int)15000
  23. }

Masking Data

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

  1. Debugger::setOutputMask([
  2.     'password' => 'xxxxx',
  3.     'awsKey' => 'yyyyy',
  4. ]);

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. Thelog() method prints out data similar to that done byDebugger::dump(), but to the debug.log instead of the outputbuffer. Note your tmp directory (and its contents) must bewritable 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 includesthe calling method, including which file and line the calloriginated from:

  1. // In PostsController::index()
  2. pr(Debugger::trace());
  3.  
  4. // Outputs
  5. PostsController::index() - APP/Controller/DownloadsController.php, line 48
  6. Dispatcher::_invoke() - CORE/src/Routing/Dispatcher.php, line 265
  7. Dispatcher::dispatch() - CORE/src/Routing/Dispatcher.php, line 237
  8. [main] - APP/webroot/index.php, line 84

Above is the stack trace generated by calling Debugger::trace() ina controller action. Reading the stack trace bottom to top showsthe 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 absolutefilepath), highlights line number $line with $context number oflines around it.

  1. pr(Debugger::excerpt(ROOT . DS . LIBS . 'debugger.php', 321, 2));
  2.  
  3. // Will output the following.
  4. Array
  5. (
  6.     [0] => <code><span style="color: #000000"> * @access public</span></code>
  7.     [1] => <code><span style="color: #000000"> */</span></code>
  8.     [2] => <code><span style="color: #000000">    function excerpt($file, $line, $context = 2) {</span></code>
  9.  
  10.     [3] => <span class="code-highlight"><code><span style="color: #000000">        $data = $lines = array();</span></code></span>
  11.     [4] => <code><span style="color: #000000">        $data = @explode("\n", file_get_contents($file));</span></code>
  12. )

Although this method is used internally, it can be handy if you’recreating your own error messages or log entries for customsituations.

  • 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 useCake\Log\Log to do logging in your application. All objects thatuse LogTrait have an instance method log() which can be usedto log messages:

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

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

  1. // At the top of the file you want to log in.
  2. use Cake\Log\Log;
  3.  
  4. // Anywhere that Log has been imported.
  5. Log::debug('Got here');

Debug Kit

DebugKit is a plugin that provides a number of good debugging tools. Itprimarily provides a toolbar in the rendered HTML, that provides a plethora ofinformation about your application and the current request. See the DebugKitDocumentation for how to install and useDebugKit.