Skip to content
PHP Ecosystem
Explore

Configuration reference

This content is not available in your language yet.

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',
'mailPath' => '@runtime/debug/mail',
],
'toolbar' => [
'position' => 'bottom',
],
],
];

These are the defaults: local access only, up to 50 retained requests, captures stored under @runtime/debug, and the .eml files of captured mail under @runtime/debug/mail. Changing routePrefix also changes the History URL, which Yii3\Debug\Middleware\DebugRouteMiddleware serves directly. Both storage paths accept a registered Yii alias and share storage.dirMode and storage.fileMode.

Choose a prefix that no application route or other debugger already owns. The debug route middleware runs before the application router and claims every path at or below that prefix, including unknown subpaths.

Yii3\Debug\Middleware\ToolbarOptions::fromParams() reads routePrefix, historySize, database.excessiveCallerThreshold, and the toolbar block once, and the container hands the same instance to both middlewares, the toolbar payload, and the debugger pages. A key you declare with the wrong type fails at startup with an InvalidArgumentException naming the key.

The package registers two middlewares in yiisoft/middleware-dispatcher.middlewares, in this order:

  • Yii3\Debug\Middleware\DebugRouteMiddleware serves the debugger pages under routePrefix and answers 403 Forbidden to a client outside allowedIPs.
  • Yii3\Debug\Middleware\RequestCaptureMiddleware captures every other request from an allowed client and injects the toolbar into HTML responses. It passes the debugger pages through uncaptured, so an application that serves them itself can register it alone.

Both write a capture still pending from an earlier request before doing anything else, whichever of the two runs first.

The application block is optional. Leave it out and the Configuration panel reads the name and version from the Composer root package, the environment from APP_ENV, and the debug mode from APP_DEBUG; every key you declare wins over the runtime value.

The debugger ships no collector or panel beyond its built-ins and names no provider package. Declare every collector and panel your application wants under yii3/debug.collectors and yii3/debug.panels, keyed by the stable ID the class reports from id():

return [
'yii3/debug' => [
'collectors' => [
'cache' => ['class' => Acme\Debug\CacheCollector::class, 'enabled' => true],
],
'panels' => [
'cache' => ['class' => Acme\Debug\CachePanel::class, 'title' => 'Cache operations', 'icon' => 'db'],
],
],
];

An entry another package’s configuration declares, such as the inertia entries yii3/inertia ships, is switched off from the application params; disable both the collector and the panel:

use PHPForge\Inertia\Debug\{InertiaCollector, InertiaPanel};
return [
'yii3/debug' => [
'collectors' => ['inertia' => ['class' => InertiaCollector::class, 'enabled' => false]],
'panels' => ['inertia' => ['class' => InertiaPanel::class, 'enabled' => false]],
],
];
  • The array key is the stable ID and must equal what the class returns from id(); a mismatch is rejected by name. Renaming a panel never changes that key, so stored captures and panel URLs stay stable.
  • A collector entry accepts class and enabled. A panel entry accepts class, title, icon, enabled, and position. Any other key is rejected by name. A plain class string is the short form of ['class' => ...].
  • enabled: false removes the entry without referencing its class, so an optional package that is not installed is not an error. Disabling a provider completely means disabling both its collector and its panel entry.
  • title and icon override the provider defaults. Only panels built on PHPForge\Debug\Panel carry an override; a panel rendering its own presentation is rejected explicitly.
  • icon is a Debug Core icon key matching [a-z0-9][a-z0-9-]*. An unknown key renders no icon.
  • position orders the Extensions group ascending; entries without one follow, sorted by effective title and then by ID. Built-in panels keep their fixed order (History, Request, Logs, Events, Profiling, Database, Mail, User, Dump, Assets) and reject position.

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.

Declare the listener of every provider collector in an events-web group, so the instance that captures the event is the same container instance the debugger reads:

use Acme\Cache\Event\CacheAccessed;
use Acme\Debug\CacheCollector;
return [
CacheAccessed::class => [CacheCollector::class],
];

The container injects its Psr\EventDispatcher\EventDispatcherInterface into PHPForge\Vite\Vite and PHPForge\Inertia\Protocol, so no further wiring is needed. Keep the debugger, Debug Core, and the provider packages up to date together in the application’s lock file.

Vite and Inertia register through the same three groups as the cache example: params declares the collector and the panel, events-web routes the provider event to the collector, and di-web builds a collector that needs the host redaction policy.

yii3/inertia ships the Inertia entries in its own configuration groups, so an application using it adds nothing:

// yii3/inertia config/params.php
'yii3/debug' => [
'collectors' => ['inertia' => InertiaCollector::class],
'panels' => ['inertia' => InertiaPanel::class],
],
// yii3/inertia config/events-web.php
ProtocolResultCreated::class => [InertiaCollector::class],
// yii3/inertia config/di-web.php, only when Debug Core is installed
InertiaCollector::class => static fn(CapturePolicy $policy): InertiaCollector
=> new InertiaCollector($policy->redact(...), $policy->redactUrl(...)),

Vite has no Yii3 adapter package, so the application declares it; ViteCollector needs no container definition:

config/params.php
use PHPForge\Vite\Debug\{ViteCollector, VitePanel};
use PHPForge\Vite\Event\AssetsResolved;
'yii3/debug' => [
'collectors' => ['vite' => ViteCollector::class],
'panels' => ['vite' => VitePanel::class],
],
// config/events-web.php
AssetsResolved::class => [ViteCollector::class],

Without the debugger installed the yii3/debug params are inert and the listener only buffers: a collector records nothing until the debugger starts it.

PHPForge\Debug\Capture\CapturePolicy holds the redaction rules the Request panel, the User identity, and the PSR-3 context of the Logs panel apply. The Inertia collector yii3/inertia declares already receives them. Hand the same rules to an application-owned collector that captures user data, in the application’s di-web group:

use Acme\Debug\CacheCollector;
use PHPForge\Debug\Capture\CapturePolicy;
return [
CacheCollector::class => static fn(CapturePolicy $capturePolicy): CacheCollector => new CacheCollector(
$capturePolicy->redact(...),
),
];

The extensions block is gone, and config/di-web.php reads collectors and panels alone. The key is ignored, so an application that still sets yii3/debug.extensions silently loses the captures of its application-owned extensions: no collector, panel, or listener is wired for them.

Before:

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

After: delete the block. The inertia flag needs no replacement, because yii3/inertia declares the Inertia collector, panel, and listener in its own configuration groups. Replace the vite flag with the Vite entries shown under Provider packages. Declare application-owned extensions under collectors and panels, keyed by the stable ID each class reports from id(), and their listeners in the application’s events-web group.

SummaryAwarePanelInterface, ContextAwarePanelInterface, and ContextAndSummaryAwarePanelInterface are gone, with their renderWithSummary(), renderWithContext(), and renderWithContextAndSummary() methods. A panel implements Yii3\Debug\Panel\ExtensionPanelInterface alone, and its single render() receives a Yii3\Debug\Panel\PanelRenderInput exposing $input->payload, $input->context, and $input->summary.

Before:

use PHPForge\Debug\Panel\PanelRenderContext;
use Yii3\Debug\Panel\ContextAwarePanelInterface;
final class CachePanel implements ContextAwarePanelInterface
{
public function render(array $payload): string
{
// renders without the debugger request context
}
public function renderWithContext(array $payload, PanelRenderContext $context): string
{
// renders with the debugger request context
}
}

After:

use Yii3\Debug\Panel\{ExtensionPanelInterface, PanelRenderInput};
final class CachePanel implements ExtensionPanelInterface
{
public function render(PanelRenderInput $input): string
{
// reads $input->payload, and $input->context or $input->summary when it needs them
}
}

Yii3\Debug\Web\PageWindow::single() is gone; PageWindow::paginate($rows, null, null) keeps every row on one page. php-forge/vite moved from require to require-dev, so an application registering the Vite panel installs the package itself.

A collector implements PHPForge\Debug\CollectorInterface — the single contract shared by the built-in collectors, the provider packages, and application-owned code — and returns the payload to persist from capture(). A panel extends PHPForge\Debug\Panel and turns that payload into a presentation. Register both under the same ID:

return [
'yii3/debug' => [
'collectors' => ['cache' => Acme\Debug\CacheCollector::class],
'panels' => ['cache' => ['class' => Acme\Debug\CachePanel::class, 'title' => 'Cache operations']],
],
];

Yii3\Debug\ExtensionRegistry also accepts instances at runtime:

$registry = $registry
->withCollector(new Acme\Debug\CacheCollector())
->withPanel(new Acme\Debug\CachePanel());

Collectors declare their own ID; the registry rejects an empty or duplicate one, and reports the IDs the configuration removed through disabled(), which a host tells apart from an ID it never knew.

RequestCaptureMiddleware runs the request with the collectors active, but it does not write the snapshot when the pipeline returns. Instead it hands a finalizer to Yii3\Debug\Capture\DeferredCapture, and the capture is written when the application dispatches Yiisoft\Yii\Http\Event\ApplicationShutdown. That event is the last step of the Yii HTTP runner, after the response is emitted and after the AfterEmit listeners of yiisoft/log and yiisoft/profiler have flushed.

Deferral is what keeps three kinds of work in the snapshot:

  • Queries issued while Yiisoft\DataResponse\DataResponse renders the view lazily, which happens only when the body is read.
  • Log messages and profiler spans flushed at AfterEmit. The debugger registers its own profiler target, so spans the profiler moved out of memory on flush still reach the Profiling and Logs panels.
  • Events dispatched after RequestCaptureMiddleware returned, such as AfterRequest and AfterEmit.

This requires the application to merge the package’s events-web configuration group, which the Yii HTTP runner loads. Rebuild the merged configuration after installing or updating the package:

Terminal window
composer yii-config-rebuild

Then confirm that the application’s merge plan (config/.merge-plan.php unless config-plugin-options.merge-plan-file says otherwise) lists yii3/debug/config/events-web.php under events-web.

If the application never dispatches that event — a console command, a custom runner, or a fatal error during emission — a PHP shutdown function registered with the first capture writes it instead, so a request is never lost.

The capture is armed before the request handler runs, so a script that ends inside the handler, through exit, dd(), or a fatal error, is still written at shutdown, as the Yii2 debugger does. It carries what was collected until then, the matched route, and the status code PHP is about to send; the response headers are empty because the application never returned a response. A handler that throws still drops its capture, so the application failure stays primary.

Without a collector coordinator there is nothing to defer, and the fallback summary is written inside the pipeline as before.

The debugger attaches itself to the services the application already declares, so no development-only DI override is needed.

  • Psr\EventDispatcher\EventDispatcherInterface is decorated by Yii3\Debug\DebugServiceProvider, published in the di-providers and di-providers-web groups. The application definition is kept; the provider only wraps what it resolves to.

  • Yiisoft\Assets\AssetLoaderInterface is decorated by the same provider, so every bundle the application loads reaches the Asset Bundles panel. The definition yiisoft/assets publishes in the di group is kept; the provider only wraps what it resolves to.

  • The bootstrap group attaches the application logger to Yiisoft\Db\Connection\ConnectionInterface when the connection accepts a logger. Independently, it instruments a PDO-backed connection that accepts a profiler with the debugger profiler. Each operation is skipped when its required service or capability is absent; an application without a connection remains valid.

  • Yiisoft\Mailer\Event\AfterSend reaches Yii3\Debug\Collector\MailCollector from the events-web group when yiisoft/mailer is installed; without it the Mail collector is not registered and the Mail panel never appears. The mailer dispatches the event only when it receives the application Psr\EventDispatcher\EventDispatcherInterface, which the yiisoft/mailer-symfony definition gets through autowiring. With that adapter installed, the body, headers, and stored file come from the Symfony email it sends, as in the Yii2 debugger. Each message is stored under storage.mailPath, downloaded from {routePrefix}/download-mail?file=<name>, and deleted when its capture leaves the history.

  • Yiisoft\User\CurrentUser is read by Yii3\Debug\Collector\UserCollector when yiisoft/user is installed; without it the User collector is not registered and the User panel never appears, and a container that defines no current user records nothing. The identity is read when the response leaves the application, before the session closes. A guest request shows the panel empty state and a Guest toolbar metric; a signed-in one shows the user ID, as in the Yii2 debugger. Identity keys the capture policy lists (such as password_hash and auth_key) are stored redacted, also inside nested arrays and objects. A failure while reading the identity never breaks the request; it is recorded as a User panel failure instead. When the container defines Yiisoft\Rbac\ManagerInterface (yiisoft/rbac), the roles and permissions assigned to the user are listed too; a manager that fails is ignored, so the identity stays inspectable.

  • The yiisoft/var-dumper default handler is decorated by Yii3\Debug\Collector\DumpCollector while a request is captured, so VarDumper::dump() and the d(), dump(), and dd() helpers keep printing through the handler the application set, and each value also appears in the Dump panel with the file and line that dumped it. The previous handler is restored when the capture ends, unless the application replaced it during the request. When symfony/var-dumper is installed and loaded first (Codeception and PsySH require it), the global dump() and dd() are Symfony’s and are not captured; d() and VarDumper::dump() still are.

Both groups must belong to the provider and bootstrap groups the application runner loads, and the decorations are idempotent, so an application wiring the connection itself keeps working.

The User panel reads the identity attributes from toArray(), then jsonSerialize() when it returns an array, then the public properties. An identity that wraps an entity exposes none of its own, so give the collector a reader in user.identityData:

use App\Identity\UserIdentity;
return [
'yii3/debug' => [
'user' => [
'identityData' => static fn(UserIdentity $identity): array => [
'id' => $identity->getId(),
...get_object_vars($identity->user),
],
],
],
];

Database capture still requires a Yii DB 2 driver. 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.

Psr\Log\LoggerInterface is not decorated. The debugger merges its debug target, and a stream target, into yiisoft/log.targets, so the application must build its logger from $params['yiisoft/log']['targets']. The yiisoft/app template already builds the logger this way; see the complete logger definition.

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 the same key to add your own, or to replace a merged one under the same name:

The example adds the optional FileTarget. Install it with composer require yiisoft/log-target-file, or replace the file entry with a target the application already provides.

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

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'],

← Back to documentation