# Debug

> Debugger and toolbar for Yii2 applications

**Debugger and toolbar for Yii2 applications**

_Pico-inspired UI, scoped CSS, light/dark mode, and 14 inspection panels_

![Debug toolbar](/docs/_astro/home-light.Qa6L9v1T.png)

:::caution
**Development only.** Never enable the debugger in production. Keep access restricted to trusted development IPs
and install production dependencies with `composer install --no-dev`.
:::

## Features

![Feature Overview](/docs/_astro/features.CPsR1VNQ.svg)

## Quick start

### Installation

The 0.2 line does not support Yii2 2.0.x.

If the Yii 22 mailer is not already a root requirement, add both packages with a scoped development flag for the mailer:

```bash
composer require yii2-extensions/debug:^0.2 yiisoft/yii2-symfonymailer:^22.0@dev --dev
```

For an existing root mailer requirement, keep its dependency section and ensure its constraint includes `@dev`;
require only `yii2-extensions/debug:^0.2` with `--dev`. See [installation](/docs/extensions/debug/installation/index.md) for entry-script
setup, asset publication and verification.

When upgrading from 0.1, review the [upgrade checklist](https://github.com/yii2-extensions/debug/blob/main/UPGRADE.md) and [migration guide](/docs/extensions/debug/migration/index.md). Keep the debugger and
`php-forge/debug-core` up to date together in the application's lock file.

### Enable the debugger

In your application's entry script, set `YII_ENV` to `dev` before loading Yii. Then register the module in
`config/web.php`, before returning `$config`:

```php
if (YII_ENV_DEV) {
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = [
        'class' => \yii\debug\Module::class,
        'allowedIPs' => ['127.0.0.1', '::1'],
    ];
}
```

Keep the registration inside the development guard. Do not bootstrap the module in production.

### Basic usage

Open an application page, expand the toolbar at the bottom, and select a panel chip to inspect the request.
Use the Yii chip for Configuration and the PHP chip for PHP info. Switch between light and dark themes from the
toolbar, and press `Escape` to close the drawer.

In Logs, messages written through the Yii 22 PSR-3 adapter `yii\log\PsrLogger` show their PSR-3 context under the
message in a collapsed "Context" disclosure; the `category` key is omitted only when it matches the row's category
shown in the Category column, while any other `category` value stays in the context.

Open the `debug/index` route to browse retained requests. Select two captures in History to compare request metrics
and panel changes, then open either capture for its details. Comparison shows structural counts without exposing
panel values.

## Configuration

The module runs with no options: up to 50 retained requests, captures under `@runtime/debug`, and a bottom toolbar.
See the [configuration reference](/docs/extensions/debug/configuration/index.md) for custom collectors and panels, the Inertia and Vite
providers, database capture, IDE links, and the standalone router.

Debug Core ships compiled assets through Composer. Consumers do not need Node.js, Foxy or an npm asset alias
for the debugger; frontend source development remains in `php-forge/debug-core`.

## Security

The toolbar and debugger routes allow `127.0.0.1` and `::1` by default. Add only trusted development addresses to
`allowedIPs`; never expose the debugger publicly. A `checkAccessCallback` can further restrict allowed requests.

Request, identity, and queue captures redact common sensitive fields, and so do Inertia captures registered with the
capture-policy closure shown in the configuration reference. In Logs, the log message is not redacted; the PSR-3
context is redacted by the capture policy. SQL diagnostics can include substituted query values. Treat stored captures
as sensitive and review them before sharing.

In the Events panel, context capture and source traces are disabled by default. This does not disable source
traces in Logs or Database.

To redact additional exact keys, extend the defaults instead of replacing them:

```php
use PHPForge\Debug\Helper\SensitiveDataRedactor;

$config['modules']['debug']['sensitiveKeys'] = [
    ...SensitiveDataRedactor::DEFAULT_KEYS,
    'tenant_signing_key',
];
```

## Browser support

Use a current browser with Web Components, native JavaScript modules, and CSS custom properties. Internet Explorer
is not supported.

## Documentation

Practical guides and complete examples for configuring the debugger and
inspecting requests.

- 📚 [Installation Guide](/docs/extensions/debug/installation/index.md)
- ⚙️ [Configuration Guide](/docs/extensions/debug/configuration/index.md)
- 💡 [Usage Examples](/docs/extensions/debug/examples/index.md)
- 🔄 [Migration Guide](/docs/extensions/debug/migration/index.md) and [Upgrade Checklist](https://github.com/yii2-extensions/debug/blob/main/UPGRADE.md)
- 🧪 [Testing Guide](/docs/extensions/debug/testing/index.md)
- [Panel Screenshots](/docs/extensions/debug/screenshots/index.md)
- [Changelog](https://github.com/yii2-extensions/debug/blob/main/CHANGELOG.md)

## AI assistance

AI agents: use the repository guides and source for the installed revision.
For a [documentation deployment](https://yii2-framework.github.io/docs/) with
`llms.txt`, read that index first. When Markdown export is enabled, append
`index.md` to a page URL. For Yii conventions, use the `yii2-framework` skill
from a local framework documentation checkout.

- 🤖 [yii2-debug-inspection skill](/docs/extensions/debug/agents/index.md): installation for Claude
  Code, Codex, and OpenCode.

Use the package-owned [skill source](https://github.com/yii2-extensions/debug/blob/main/skills/yii2-debug-inspection/SKILL.md) to
configure and verify the debugger.
Installing the Composer package alone does not activate a skill from
`vendor/`.

If the hosted sources are unavailable, use the repository guides and locally
available skills.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)
[Join our Subreddit](https://www.reddit.com/r/Yii2/)
[Join on Telegram](https://t.me/yii_framework_in_english)

## License

[License](https://github.com/yii2-extensions/debug/blob/main/LICENSE)

## Package

- Source code and issues: [yii2-extensions/debug](https://github.com/yii2-extensions/debug). Star the repository if the package is useful to you.
- Composer package: [yii2-extensions/debug](https://packagist.org/packages/yii2-extensions/debug).
- Changelog: [CHANGELOG.md](https://github.com/yii2-extensions/debug/blob/main/CHANGELOG.md).