# DebugKit: a CakePHP toolbar that disables itself when it thinks you are not local

> DebugKit is the CakePHP plugin that puts a toolbar on your page showing configuration, log messages, SQL queries and timing data. Its most interesting feature is a guardrail: the toolbar will not appear on a hostname it does not recognise as a development environment.

**cakephp/debug_kit** — Debug Toolbar for CakePHP applications.

- Repository: https://github.com/cakephp/debug_kit
- Website: https://book.cakephp.org/debugkit/
- Stars: 839 · Forks: 564
- Language: PHP
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/cakephp-debug-kit

## A toolbar for configuration, logs, SQL and timing

DebugKit provides a debugging toolbar and enhanced debugging tools for CakePHP applications, and the README summarises what you get as four things: configuration data, log messages, SQL queries and timing data.

That list is the whole product. There is no profiler, no flame graph and no APM. It is a panel on the bottom right of every page that accumulates the state of the request you just made, and the value is in the aggregation: the queries a single page view ran, how long each of them took, what the configuration resolved to, and what the log captured.

The repository layout shows what that takes. There is src/ for the plugin classes, templates/ for the panel views, webroot/ for the JavaScript and CSS that the injected panel needs, config/ for the plugin's own configuration, docs/ for the documentation site, and tests/ for the test suite. The webroot/js directory holds main.js, inject-iframe.js and a modules/ subdirectory, and the package.json carries an ESLint configuration for exactly those three paths, which is a reminder that the toolbar is a front end as well as a PHP plugin.

The project also publishes a documentation site, and the Dockerfile at the root builds it with VitePress on Node 24 and serves the result with angie, exposing port 80 with a wget based health check.

## Installed as a dev dependency and loaded only in debug mode

Installation is two steps, and both are deliberate about keeping the plugin out of production.

The first is a Composer require from the root directory of your CakePHP project, where the composer.json file lives, and the version constraint is pinned to the 5.x line:

```sh
php composer.phar require --dev cakephp/debug_kit:"^5.0"
```

The --dev flag is the important part. It puts the plugin in the development dependency section, so a deployment that installs without dev dependencies never has the code at all.

The second step loads the plugin, and the flag here does the actual protecting:

```sh
bin/cake plugin load DebugKit --only-debug
```

With --only-debug, the plugin is loaded when the application is running in debug mode and skipped otherwise. The README's warning at the top is emphatic about the limits: DebugKit is only intended for use in single-user local development environments, and you should avoid using it in shared development environments, in staging, or in any environment where you need to keep configuration data and environment variables hidden.

That is a stronger statement than most tooling makes, and it is the right one here, because a panel that shows configuration and environment variables is exactly the thing that leaks credentials when it turns up in the wrong place.

## SQLite by default, and three reasons the panel does not appear

DebugKit needs a database of its own to keep its collected data. The requirement is SQLite with the pdo_sqlite driver, or another database driver CakePHP can talk to, and by default DebugKit uses SQLite. If you need a different database, the documentation has a Database Configuration section for it.

The README then has a section headed Is DebugKit not working?, and it is more useful than most troubleshooting sections because the failure is silent. If you do not see a CakePHP icon on the bottom right of your page, DebugKit is not working correctly. There are three common causes.

The first is that your PHP environment does not have SQLite installed. The advice is to check your application logs to confirm it, and then either configure DebugKit to use a different database or install the PDO SQLite 3 extension.

The second is the hostname. Your hostname has to be added to the DebugKit.safeTld setting, and if your local domain is not a known development environment name, DebugKit will disable itself to protect a potentially non-development environment. In other words, the absence of the panel can be a safety decision rather than a broken install.

The third is integration with another plugin. If you are using the Authorization plugin, you need to set DebugKit.ignoreAuthorization to true in your config.

Two of these three are configuration in a file you have to edit, and one is a PHP extension you have to install. All three produce the same symptom.

## The guardrail is a top level domain list, not a debug flag

The safeTld setting deserves its own look, because it is the mechanism that separates a developer machine from a shared environment and it is unusual to see it implemented this way.

A top level domain list is a short set of names under which any hostname is treated as local. A developer running the application at myapp.test, or at project.localhost, is inside a domain that is unambiguously a development name, so the plugin can safely assume it is not in front of a real user. Anything outside that list, such as a staging hostname on a company domain, is refused.

Compare that with the usual alternative, where a debug flag decides everything. A flag is easy to leave on, because it is one boolean that has to be turned off deliberately, and the same flag usually governs your framework's own error pages. A hostname list fails closed in a different way: the panel appears only for names you have explicitly decided are development names, and it appears on every one of your local aliases at once.

The cost of that choice is the third troubleshooting item in the README. If your local domain is unusual, nothing happens and the reason is not obvious from a browser. The fix is to add your hostname to DebugKit.safeTld, and the README is explicit that the panel will not show otherwise.

## Panels can come from other plugins, and the toolbar is a container

DebugKit's panel system is extensible in a way that is worth noting, because it explains the shape of the product. The README lists panels contributed by other plugins: an L10n panel by the Setup plugin, which shows the current localization for Date, DateTime and Time objects and values, and a Twig panel by the Twig plugin, which lists all templates.

Both examples are cheap and diagnostic. The localization panel answers the question that comes up constantly when a date renders in the wrong format, and the template list answers the question of which template actually handled a given URL. Neither is a feature DebugKit would implement itself, because both depend on another plugin's domain.

The Docker Compose file in the repository is not a development environment for the plugin itself, and it is worth noticing that the Dockerfile builds the documentation site rather than the plugin. The plugin runs inside a CakePHP application, which is the only place it makes sense.

The rest of the repository is the tooling a mature PHP project accumulates: phpcs.xml for coding standards, phpstan.neon with a phpstan-baseline.neon, psalm.xml with a psalm-baseline.xml, phpunit.xml.dist for the test configuration, a .phive/ directory for tool management, an .editorconfig, an .eslintrc.json, and composer.json alongside a package.json for the JavaScript half of the panel.

## Two release lines, MIT terms, and a moving branch

DebugKit is MIT licensed, with the LICENSE.txt file at the root of the repository and an MIT badge in the README, although the repository is classified with a custom licence that GitHub cannot categorise. Read LICENSE.txt for the terms that actually apply, and this is not legal advice.

The release pattern shows two lines in maintenance at once. The tags include DebugKit 5.2.4 on 2026-06-06, DebugKit 4.10.3 on 2026-06-06 and DebugKit 5.2.3 on 2026-05-31, with the 4.x line receiving a release on the same day as the 5.2.4 patch. The default branch is 5.x, and the installation instructions pin the constraint to the 5.x line with the caret requirement.

The last push to the repository was on 2026-10-16 and it is not archived, so work continues between releases. A version map in the project wiki links older versions, which is the standard approach for a plugin that has been around long enough to have accumulated several generations of supported CakePHP.

Documentation lives in the CakePHP book at book.cakephp.org/debugkit, and the README links a roadmap wiki page for anyone who wants to see what is planned before contributing.

## Where DebugKit is the wrong tool

The first wrong fit is any environment that is not a single developer's own machine. The README says it directly: not shared development environments, not staging, and not anywhere you need configuration data and environment variables to stay hidden. The panel shows configuration data by design, and no flag combination makes that safe in a shared environment, only absent.

The second wrong fit is a performance question. DebugKit gives you SQL queries and timing data for the request in front of you. That is enough to find the obviously slow query and enough to see that a page makes forty of them. It is not a profiler, it does not attribute time to your PHP code, and it does not sample or aggregate over time. If the question is where the seconds go in a slow endpoint under production traffic, a real profiler is the tool, and DebugKit is not a substitute for it.

The third is a team that wants history rather than a snapshot. The toolbar is request scoped and ephemeral. The alternative in plain CakePHP terms is to read the framework's own logs, which the README points you at for diagnosing the SQLite problem, and to use a query log rather than a panel. That approach costs you the in-page view of configuration and the aggregated timing, and in exchange it works everywhere, including on a shared host where a toolbar cannot be enabled, and it keeps a record after the request is over.

The fourth is a project that wants to add panels of its own without a plugin boundary. The panel system is designed to be extended by plugins, which is the right design for the ecosystem, but it means a panel you write yourself has to live inside a plugin, with its own composer package and its own release cycle.

## Conclusion

DebugKit fits a CakePHP developer working on their own machine who wants request scoped visibility into SQL, timing, logs and configuration without reading log files. It does not fit a shared staging environment or any setup where configuration and environment variables must stay hidden, and the plugin itself says so. Before you rely on the toolbar, confirm that your local hostname passes DebugKit.safeTld and that the PHP build has pdo_sqlite, since either one silently hides the panel.

## FAQ

### What does CakePHP DebugKit show?

It provides a debugging toolbar that lets you see configuration data, log messages, SQL queries and timing data for your application. The panel appears as a CakePHP icon on the bottom right of the page.

### How do I install DebugKit?

From the root of your CakePHP project run php composer.phar require --dev cakephp/debug_kit:"^5.0", then load the plugin with bin/cake plugin load DebugKit --only-debug. The dev dependency and the only-debug flag keep it out of production.

### Why is the DebugKit toolbar not showing?

Three common causes are documented: your PHP environment does not have SQLite installed, your hostname is not in the DebugKit.safeTld setting so the plugin disables itself, or you are using the Authorization plugin and need DebugKit.ignoreAuthorization set to true.

### Can I use DebugKit on a staging server?

No. The README states that DebugKit is only intended for single-user local development environments, and that you should avoid it in shared development environments, staging, or any environment where configuration data and environment variables need to stay hidden.

### Which licence is DebugKit released under?

The project is MIT licensed, with the LICENSE.txt file at the root of the repository, and the README carries an MIT badge. The current release line is 5.x.

## Sources

- [cakephp/debug_kit on GitHub](https://github.com/cakephp/debug_kit)
- [Issues](https://github.com/cakephp/debug_kit/issues)
- [Project website](https://book.cakephp.org/debugkit/)
- [README](https://github.com/cakephp/debug_kit/blob/5.x/README.md)
- [Releases](https://github.com/cakephp/debug_kit/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cakephp-debug-kit