README

Yii Framework

Debug

Debugger and toolbar for Yii3 applications
Shared Debug Core UI, scoped CSS, light/dark mode, and application-registered extension 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

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:

composer yii-config-rebuild

Applications that build their middleware list by hand must spread the merged $params['yiisoft/middleware-dispatcher']['middlewares'] first, so the toolbar middleware stays in the pipeline. The middleware also answers the /debug pages itself, so the debugger publishes no routes and needs none of your application's routing.

The debugger attaches itself to Yiisoft\Db\Connection\ConnectionInterface and Psr\EventDispatcher\EventDispatcherInterface through the container, using the di-providers and bootstrap configuration groups; both must belong to the provider and bootstrap groups your runner loads. Your services keep their own definitions and the debugger only decorates them, so a custom PSR dispatcher needs no separate integration.

The Logs panel works through parameters instead: the debugger merges its debug target, and a stream target, into yiisoft/log.targets, so your application must build Psr\Log\LoggerInterface from $params['yiisoft/log']['targets']. The yiisoft/app template already builds the logger this way:

'targets' => ReferencesArray::from(
    array_values($params['yiisoft/log']['targets'] ?? [StreamTarget::class]),
),

An application that hardcodes its target list keeps working, but its Logs panel stays empty. A template that relies on the ?? [StreamTarget::class] fallback needs no parameters of its own: the merged key bypasses that fallback, yet it already carries a stream target beside the debugger's. Declare targets under that key to add your own, or to replace a merged one under the same name:

'yiisoft/log' => [
    'targets' => [
        'file' => \Yiisoft\Log\Target\File\FileTarget::class,
    ],
],

The snapshot itself is written when the application dispatches Yiisoft\Yii\Http\Event\ApplicationShutdown, through the merged events-web listeners the Yii HTTP runner uses. Finalizing there, rather than inside the middleware pipeline, is what makes the logs, the profiler spans flushed after emission, and the queries issued while the view is rendered lazily complete in the capture. See Capture lifecycle.

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 for registering collectors and panels, provider integrations such as Inertia and Vite, database thresholds, and IDE links.

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