# Yii3 Debug

> Debugger and toolbar for Yii3 applications

Package entry: `yii3/debug`. Requires PHP `>=8.3`, Yii3 `Yii 3 application using Yii Config Plugin`. Checked 2026-10-29. [View the entry in the package directory](</docs/packages/yii3/debug/index.md>)

**Debugger and toolbar for Yii3 applications**

_Shared Debug Core UI, scoped CSS, light/dark mode, and application-registered extension panels_

:::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: request history, logs and events, profiling, database, toolbar, and Inertia/Vite extensions](/docs/_astro/features.F2iwE0sh.svg)

## Quick start

### Installation

Requires PHP 8.3 or newer and a Yii 3 application using Yii Config Plugin. Version 0.1.0 is available as a stable
Composer release. The debugger is development-only runtime tooling, so keep it in the development dependency set:

```shell
composer require --dev "yii3/debug:^0.1"
```

The `^0.1` constraint selects stable releases from `0.1.0` up to, but not including, `0.2.0`. A stable Composer version
does not promise API compatibility with future 0.x minor lines.

The application must already provide the `yiisoft/router-implementation` and `yiisoft/db-implementation` virtual
packages. Keep its existing router and database driver; if either provider is absent, choose one that matches the
application before retrying installation.

### Integrate the application

Run the application with `APP_ENV=dev`. The debugger also accepts `debug` and `test`; it stays disabled when the
runtime environment is missing, unknown, or production. Setting the runner's configuration environment alone is
not enough.

Rebuild the merged configuration after installing or updating the package:

```shell
composer yii-config-rebuild
```

Installation publishes configuration, but the application still owns its aggregate configuration groups, logger, and
middleware list. Complete the [Getting started guide](/docs/extensions/yii3-debug/getting-started/index.md) to connect all of them. Installing the package or
seeing it in the merge plan alone does not prove that the debugger can resolve from the container or capture a request.

### 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.

Open `/debug` 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 debugger runs with its default options out of the box. See the
[configuration reference](/docs/extensions/yii3-debug/configuration/index.md) for options, collectors and panels, provider integrations such as
Inertia and Vite, database thresholds, and IDE links. See the [application integration examples](/docs/extensions/yii3-debug/examples/index.md) for
copyable container, logger, middleware, and runner recipes.

## Security

The toolbar and debugger routes allow `127.0.0.1` and `::1` by default. Access checks use the direct client address,
not forwarded proxy headers. Add only trusted development addresses to `allowedIPs`; never expose the debugger publicly.

Request captures redact sensitive fields and URL query values; hand the same capture policy to a provider collector that
records user data, as the configuration reference shows. 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 affect source traces in Logs or Database.

## Documentation

- 📚 [Getting started](/docs/extensions/yii3-debug/getting-started/index.md)
- ⚙️ [Configuration reference](/docs/extensions/yii3-debug/configuration/index.md)
- 💡 [Application integration examples](/docs/extensions/yii3-debug/examples/index.md)
- 🖼️ [Panel screenshots](/docs/extensions/yii3-debug/screenshots/index.md)
- 🤖 [AI assistance](/docs/extensions/yii3-debug/agents/index.md)
- 🧪 [Testing guide](/docs/extensions/yii3-debug/testing/index.md)

## AI assistance

AI agents should start with the [documentation index](/docs/extensions/yii3-debug/getting-started/index.md) and use the package-owned
[`yii3-debug-integration` skill](/docs/extensions/yii3-debug/agents/index.md) for installation, container wiring, and functional verification. The
[hosted Yii3 Debug documentation](https://yii2-framework.github.io/docs/extensions/yii3-debug/) publishes this adapter;
do not substitute the similarly named `yii2-extensions/debug` guide or its Yii 2 module APIs.

Match the guidance to the installed package files. If a hosted source is unavailable or does not match, use the
[repository guides](#documentation), [skill source](https://github.com/yii3/debug/blob/main/skills/yii3-debug-integration/SKILL.md), source PHPDoc, and
[changelog](https://github.com/yii3/debug/blob/main/CHANGELOG.md).

## 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/yii3/debug/blob/main/LICENSE)

## Package

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