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

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:

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 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 for options, collectors and panels, provider integrations such as Inertia and Vite, database thresholds, and IDE links. See the application integration examples 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

AI assistance

AI agents should start with the documentation index and use the package-owned yii3-debug-integration skill for installation, container wiring, and functional verification. The hosted Yii3 Debug documentation 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, skill source, source PHPDoc, and changelog.