# CakePHP DebugKit [![Build Status](https://secure.travis-ci.org/cakephp/debug_kit.png?branch=master)](http://travis-ci.org/cakephp/debug_kit)

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

## Requirements

The master branch has the following requirements:

* CakePHP 2.2.0 or greater.
* PHP 5.3.0 or greater.

## Installation

_[Using [Composer](http://getcomposer.org/)]_

Add the plugin to your project's `composer.json` - something like this:

```javascript
{
  "require": {
    "cakephp/debug_kit": "2.2.*"
  }
}
```

Because this plugin has the type `cakephp-plugin` set in it's own `composer.json`, composer knows to install it inside your `/Plugin` directory, rather than in the usual vendors file. It is recommended that you add `/Plugin/DebugKit` to your .gitignore file. (Why? [read this](http://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md).)

> Consider using "require-dev" if you only want to include DebugKit for your development environment.

_[Manual]_

* Download the [DebugKit archive](https://github.com/cakephp/debug_kit/zipball/2.2).
* Unzip that download.
* Rename the resulting folder to `DebugKit`
* Then copy this folder into `app/Plugin/`

_[GIT Submodule]_

In your app directory type:

```bash
git submodule add --branch 2.2 git://github.com/cakephp/debug_kit.git Plugin/DebugKit
git submodule init
git submodule update
```

_[GIT Clone]_

In your plugin directory type

```bash
git clone --single-branch --branch 2.2 git://github.com/cakephp/debug_kit.git DebugKit
```

### Enable plugin

* In 2.x you need to enable the plugin your `app/Config/bootstrap.php` file. If you are already using `CakePlugin::loadAll();`, then the following is not necessary.:
```php
    CakePlugin::load('DebugKit');
```
* Include the toolbar component in your `app/Controller/AppController.php`:
```php
class AppController extends Controller {
         public $components = array('DebugKit.Toolbar');
}
```
* Set `Configure::write('debug', 1);` in `app/Config/core.php`.
* Make sure to remove the 'sql_dump' element from your layout (usually
  `app/View/Layouts/default.ctp`), if you want to experience the awesome that is
  the DebugKit SQL log.

## Reporting Issues

If you have a problem with DebugKit please open an issue on [GitHub](https://github.com/cakephp/debug_kit/issues).

## Contributing

If you'd like to contribute to DebugKit, check out the
[roadmap](https://github.com/cakephp/debug_kit/wiki/roadmap) for any
planned features. You can [fork](https://help.github.com/articles/fork-a-repo)
the project, add features, and send [pull
requests](https://help.github.com/articles/using-pull-requests) or open
[issues](https://github.com/cakephp/debug_kit/issues).

## Versions

DebugKit has several releases, each compatible with different releases of
CakePHP. Use the appropriate version by 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.
* `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.
  You can also use the `master` branch to get the most recent updates.
* `2.2.x` are compatible with CakePHP 2.2.0 and greater. It is a necessary
  upgrade for people using CakePHP 2.4 as the naming conventions around loggers
  changed in that release.

# Documentation

## Toolbar Panels

The DebugKit Toolbar is comprised of several panels, which are shown by clicking the
CakePHP icon in the upper right-hand corner of your browser after DebugKit has been
installed and loaded. 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
your own custom panels.

### Built-in 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
   `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.
 * **Environment** Display environment variables related to PHP + CakePHP.

## Configuration

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

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

### Configuring Panels

You can customize the toolbar to show your custom panels or hide any built-in panel when adding it toolbar to your components.
```php
public $components = array('DebugKit.Toolbar' => array(
    'panels' => array('MyCustom', 'timer'=>false)
    )
);
```

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

#### Controlling Panels

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.
```php
public $components = array(
        'DebugKit.Toolbar' => array('panels' => array('MyCustom', '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.
```php
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.

#### forceEnable

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

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.
```php
public $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.

## Developing Your Own Panels

You can create your own custom panels for DebugKit to help in debugging your applications.

### Panel Classes

Panel Classes simply need to be placed in`Panel` 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`.
```php

App::uses('DebugPanel', 'DebugKit.Lib');

/**
 * My Custom Panel
 */
class MyCustomPanel extends DebugPanel {
        ...
}
```
See also the example `Test/test_app/Plugin/DebugkitTestPlugin/Lib/Panel/PluginTestPanel.php`.

Notice that custom panels are required to subclass the `DebugPanel` class. Panels can define the
`css` and `javascript` properties to include additional CSS or javascript on the page. Both
properties should be an array.
```php
class MyCustomPanel extends DebugPanel {
        public $javascript = array(
                '/my_plugin/js/custom_panel.js'
        );
}
```

### Callbacks

Panel objects have 2 callbacks, that allow them to hook into and introspect on the current request.
```php
startup(Controller $controller)
```

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

Much like `startup()` `beforeRender()` is called 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.

#### Example of beforeRender Callback
```php
/**
 * beforeRender callback - grabs request params
 *
 * @return array
 */
 public 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`

### Panel Elements

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 `View/Elements` directory.

#### Custom Titles and Elements

Panels should pick up their title and element name by convention. 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.

### Panels as Cake Plugins

Panels provided by [Cake Plugins](http://book.cakephp.org/2.0/en/plugins.html) work almost entirely the same as other plugins, with one minor difference:  You must set `public $plugin` to be the name of the plugin directory, so that the panel's Elements can be located at render time.
```php
class MyCustomPanel extends DebugPanel {
    public $plugin = 'MyPlugin';
        ...
}
```

To use a plugin panel, use the common CakePHP dot notation for plugins.
```php
public $components = array('DebugKit.Toolbar' => array(
    'panels' => array('MyPlugin.MyCustom')
));
```
The above would load all the default panels as well as the custom panel from `MyPlugin`.

## Cache Engine

By default, DebugKit uses File as the engine for internal caching, but if you want to use another cache engine you can customize it by simply adding a cache key inside the components config array.
```php
public $components = array('DebugKit.Toolbar' => array(
        'cache' => array('engine' => 'Memcache', 'servers' => array('127.0.0.1:11211'))
        )
);
```

You can use any cache engine supported by CakePHP, the same way you set in both core.php and bootstrap.php files with the Cache::config() method.

## Viewing the Toolbar for AJAX Requests

When doing AJAX requests, you will not be able to see an HTML version of the toolbar. However, if you have a browser extension that supports FirePHP, you can view
the toolbar in your browser:

- [FirePHP 4 chrome](https://chrome.google.com/webstore/detail/firephp4chrome/gpgbmonepdpnacijbbdijfbecmgoojma)
- [FirePHP for chrome](https://chrome.google.com/webstore/detail/firephp-for-chrome/goajlbdffkligccnfgibeilhdnnpaead)
- [FirePHP for firefox](https://addons.mozilla.org/en-US/firefox/addon/firephp/)

Once you have installed the correct extension, you should see the toolbar data output on each AJAX request.