README

Yii Framework

Debug

Debugger and toolbar for Yii3 applications
Shared Debug Core UI, scoped CSS, light/dark mode, and opt-in Inertia/Vite panels

Yii3 application with the debug toolbar

Warning

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

Quick start

Installation

Requires PHP 8.3 or newer and a Yii3 application using Yii Config Plugin.

composer require yii3/debug --dev

Enable the debugger

Set the vendor override layer in your application's composer.json, keeping any existing extra settings:

{
    "extra": {
        "config-plugin-options": {
            "vendor-override-layer": "yii3/debug"
        }
    }
}

Rebuild the application configuration after changing this setting:

composer yii-config-rebuild

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.

The package registers its routes, toolbar middleware, logging, and event capture automatically. Your application must use the merged yiisoft/middleware-dispatcher.middlewares parameters for its middleware pipeline. If it defines its own logger, preserve the targets in yiisoft/log.targets; custom PSR loggers and event dispatchers need a separate integration.

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

Override only the options you need in your application's parameters:

return [
    'yii3/debug' => [
        'allowedIPs' => ['127.0.0.1', '::1'],
        'historySize' => 50,
        'routePrefix' => '/debug',
        'storage' => [
            'path' => '@runtime/debug',
        ],
        'toolbar' => [
            'position' => 'bottom',
        ],
    ],
];

These are the defaults: local access only, up to 50 retained requests, and captures stored under @runtime/debug. Changing routePrefix also changes the History URL. The storage path accepts a registered Yii alias.

Inertia and Vite

Enable either integration when your application uses the corresponding package:

return [
    'yii3/debug' => [
        'extensions' => [
            'inertia' => true,
            'vite' => true,
        ],
    ],
];

Both are disabled by default. Inertia requires a compatible yii3/inertia ^0.1 revision providing Yii3\Inertia\ResolvedPageObserver. Vite uses the application's existing php-forge/vite configuration and entrypoints. Keep the debugger, Debug Core, and enabled integration packages up to date together in the application's lock file.

An extension appears in the sidebar only when the selected request contains its data. Vite's Production label means it is inspecting built assets in your development application, not that the debugger can run in production.

Database

Database capture requires a Yii DB 2 driver and an instrumented application connection. For example, if your SQLite application already registers its configured connection as Yiisoft\Db\Sqlite\Connection, add this factory to your development-only DI configuration. The container supplies that connection and the debugger's registered profiler:

use Yii3\Debug\Db\DebugDbProfiler;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Sqlite\Connection;

return [
    ConnectionInterface::class => static function (
        Connection $connection,
        DebugDbProfiler $debugDbProfiler,
    ): ConnectionInterface {
        $debugDbProfiler->instrument($connection);

        return $connection;
    },
];

Keep the existing concrete Connection registration and its driver settings; it must not resolve back to ConnectionInterface. For another PDO driver, use its configured concrete connection class instead of SQLite's. EXPLAIN supports MySQL, SQLite, and PostgreSQL and requires the application's Yiisoft\Db\Connection\ConnectionInterface binding to match the captured queries. Leave EXPLAIN unconfigured when one binding cannot represent all captured connections.

IDE links

Source traces use ide:// links by default. Set traceLine to false for plain file names and line numbers, or provide your editor's URL template in the yii3/debug parameters:

'traceLine' => '<a href="phpstorm://open?file={file}&line={line}">{text}</a>',

For containers or remote environments, map captured paths to your local project:

'tracePathMappings' => ['/var/www/html' => '/home/developer/projects/app'],

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 and Inertia captures redact sensitive fields and URL query values. Logs preserve original diagnostic values and are not 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.