DebugKit provides a debugging toolbar and enhanced debugging tools for CakePHP applications.

• Clone/Copy the files in this directory into app/Plugin/DebugKit
• Ensure the plugin is loaded in app/Config/bootstrap.php by calling CakePlugin::load('DebugKit');
• Include the toolbar component in your AppController.php:
  • public $components = array('DebugKit.Toolbar');
• Set debug mode to at least 1.
• Make sure to remove the 'sql_dump' element from your layout if you want to experience the awesome that is the debug kit SQL log.

If you have an issues with DebugKit please open a ticket on lighthouse http://cakephp.lighthouseapp.com/projects/42880-debug-kit/overview

If you'd like to contribute to DebugKit, check out the Roadmap for any planned features. You can fork the project add features and send pull requests, or open tickets on lighthouse.

DebugKit has several releases, they are compatible with different release of CakePHP. Downloading a tag, or checking out the correct branch.

• 1.0, 1.1, 1.2 are compatible with CakePHP 1.2.x. These releases of DebugKit will not work with CakePHP 1.3. You can also use the 1.2-branch for the mos recent updates and bugfixes.
• 1.3.0 is compatible with CakePHP 1.3.x only. It will not work with CakePHP 1.2. You can also use the 1.3 branch to get the most recent updates and bugfixes.
• 2.0.0 is compatible with CakePHP 2.0.x only. It will not work with previous CakePHP versions. You can also use the master branch to get the most recent updates.
• 2.2.0 is compatible with CakePHP 2.2.0 and greater. It will not work with older versions of CakePHP as this release uses new API's available in 2.2.

The debugKit Toolbar is comprised of several panels. Each panel is comprised of a panel class and view element. Typically a panel handles the collection and display of a single type of information such as Logs or Request information. You can choose to panels from the toolbar or add you own custom panels.

There are several built-in panels. They are

• History Allows access to previous request information, useful when debugging actions with redirects.
• Request Displays information about the current request, GET, POST, Cake Parameters, Current Route information and Cookies if the CookieComponent is in you controller's components.
• Session Display the information currently in the Session.
• Timer Display any timers that were set during the request see [wiki:debugkitdebugger DebugKitDebugger] for more information. Also displays memory use at component callbacks as well as peak memory used.
• Sql Logs Displays sql logs for each database connection.
• Log Display any entries made to the log files this request.
• Variables Display View variables set in controller.

You can create your own panels as well to provide custom debugging information for your application. Custom panels need to subclass the DebugPanel class. Panel objects have 2 callbacks that allow them to hook into and introspect on the current request.

startup(Controller $controller)

Each panel's startup() method is called during component startup() process. $controller is a reference to the current controller object.

beforeRender(Controller $controller)

Much like startup() beforeRender() is callled during the Component beforeRender() process. Again $controller is a reference to the current controller. Normally at this point you could do additional introspection on the controller. The return of a panels beforeRender() is automatically passed to the View by the Toolbar Component. Therefore, under normal use you do not need to explicitly set variables to the controller.

Panel Classes simply need to be placed inPanel directory inside a Lib path. The filename should match the classname. So the class MyCustomPanel would be expected to have a filename of app/Lib/Panel/MyCustomPanel.php.

/**
 * beforeRender callback - grabs request params
 *
 * @return array
 **/
	function beforeRender(Controller $controller) {
		return $controller->params;
	}

This would return cake's internal params array. The return of a panel's beforeRender() is available in you Panel element as $content

Panels provided by plugins work almost entirely the same as other plugins, with one minor difference. You must set var $plugin to be the plugin name directory. This must be done so that the element can be located at rendering time.

To use a plugin panel, use the common CakePHP dot notation for plugins.

public $components = array('DebugKit.Toolbar' => array(
    'panels' => 'MyPlugin.Custom'
));

The above would load all the default panels as well as the custom panel from MyPlugin.

Each Panel is expected to have a view element that renders the content from the panel. The element name must be the underscored inflection of the class name. For example SessionPanel has an element named session_panel.ctp, and sqllogPanel has an element named sqllog_panel.ctp. These elements should be located in the root of your views/elements directory. If you are creating panels as part of your plugin see above for Using panels from plugins.

Panels are usually use conventions for defining their title and element name. However, if you need to choose a custom element name or title, there are properties to allow that configuration.

• $title - Set a custom title for use in the toolbar. This title will be used as the panels button.
• $elementName - Set a custom element name to be used to render the panel.

The toolbar has a few configuration settings. Settings are passed in the component declaration like normal component configuration.

public $components = array(
	'DebugKit.Toolbar' => array(/* array of settings */)
);

You can customize the toolbar to show your custom panels or hide any built-in panel when adding it toolbar to your components.

public $components = array('DebugKit.Toolbar' => array(
	'panels' => array('customPanel', 'timer'=>false)
	)
);

Would display your custom panel and all built-in panels except the 'Timer' panel.

Using the panels key you can specify which panels you want to load, as well as the order in which you want the panels loaded.

public $components = array(
	'DebugKit.Toolbar' => array('panels' => array('myCustomPanel', 'timer' => false))
);

Would add your custom panel myCustomPanel to the toolbar and exclude the default Timer panel. In addition to choosing which panels you want, you can pass options into the __construct of the panels. For example the built-in History panel uses the history key to set the number of historical requests to track.

public $components = array(
	'DebugKit.Toolbar' => array('history' => 10)
);

Would load the History panel and set its history level to 10. The panels key is not passed to the Panel constructor.

The forceEnable setting is new in DebugKit 1.1. It allows you to force the toolbar to display regardless of the value of Configure::read('debug');. This is useful when profiling an application with debug kit as you can enable the toolbar even when running the application in production mode.

autoRun is a new configuration setting for DebugKit 1.2. It allows you to control whether or not the toolbar is displayed automatically or whether you would like to use a query string parameter to enable it. Set this configuration key to false to use query string parameter toggling of the toolbar.

var $components = array(
    'DebugKit.Toolbar' => array('autoRun' => false)
);

When visiting a page you can add ?debug=true to the url and the toolbar will be visible. Otherwise it will stay hidden and not execute.