yii3/debug

Yii3 adapter for the PHP Forge debug core.

dev-main / 0.1.x-dev 2026-08-19 11:17 UTC

Requires

• php: >=8.3
• composer-runtime-api: ^2.2
• ext-mbstring: *
• php-forge/debug-core: ^0.1@dev
• psr/container: ^2.0
• psr/event-dispatcher: ^1.0
• psr/http-factory: ^1.1
• psr/http-message: ^1.1 || ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0
• ui-awesome/html: ^0.6
• ui-awesome/html-core-component: ^0.4
• ui-awesome/html-interop: ^0.4
• yiisoft/aliases: ^3.1
• yiisoft/assets: ^5.1
• yiisoft/data: ^2.0
• yiisoft/definitions: ^3.4
• yiisoft/html: ^3.0 || ^4.0
• yiisoft/http: ^1.3
• yiisoft/log: ^2.2
• yiisoft/router: ^4.0
• yiisoft/view: ^12.2
• yiisoft/yii-dataview: ^1.1

Requires (Dev)

• guzzlehttp/psr7: ^2.7
• infection/infection: ^0.34
• maglnet/composer-require-checker: ^4.1
• php-forge/baseline: ^0.1
• php-forge/coding-standard: ^0.3
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0.3
• phpunit/phpunit: ^12.5
• yii2-extensions/scaffold: ^0.2
• yiisoft/csrf: ^2.2
• yiisoft/db: ^2.0@dev || ^1.3
• yiisoft/di: ^1.4
• yiisoft/rbac: ^2.1
• yiisoft/router-fastroute: ^4.0
• yiisoft/session: ^3.0
• yiisoft/user: ^2.2

Suggests

• yiisoft/csrf: Embeds the CSRF token into the user-switch forms.
• yiisoft/db: Enables the Database panel: bind Yii3\Debug\Collector\DbCollector as the connection profiler.
• yiisoft/rbac: Enables role and permission capture in the User panel: wire Yiisoft\Rbac\ManagerInterface.
• yiisoft/session: Required by the user-switch main-user tracking.
• yiisoft/user: Enables the User panel and the user-switch actions.

BSD-3-Clause

• Wilmer Arambula

• php
• debug
• debugger
• developer-tools
• yii3

Published on Packagist.org on 2026-08-19 11:17 UTC

README

Yii3 adapter for php-forge/debug-core.

The adapter implements Yii3 collectors locally and stores their typed output in the same versioned snapshot format used by the Yii2 adapter.

Installation

composer require yii3/debug --dev

The package contributes the shared snapshot store plus /debug, /debug/view, and /debug/toolbar routes automatically when Yii Config Plugin is enabled.

Register Yii3\Debug\Middleware\ToolbarMiddleware as the first application middleware so it wraps the error handler and can inject the toolbar into every eligible HTML response:

'withMiddlewares()' => [
    [
        \Yii3\Debug\Middleware\ToolbarMiddleware::class,
        \Yiisoft\ErrorHandler\Middleware\ErrorCatcher::class,
        // Remaining application middleware.
    ],
],

The toolbar and debug pages accept requests from 127.0.0.1 and ::1 by default. Configure allowedIPs explicitly when the development application runs behind a trusted container or proxy.

The default path is runtime/debug, relative to the application's working directory. Override it in application parameters when an absolute runtime path is required:

return [
    'yii3/debug' => [
        'path' => '/absolute/path/to/runtime/debug',
        'historySize' => 50,
        'dirMode' => 0775,
        'fileMode' => 0664,
        'allowedIPs' => ['127.0.0.1', '::1'],
    ],
];

Custom collectors and panels

Implement PHPForge\Debug\Collector\CollectorInterface in the application and return a typed PHPForge\Debug\Storage\PanelSnapshot. An optional Yii3\Debug\Panel\PanelInterface with the same stable ID can provide navigation metadata and render the stored payload. Add both class names to the package DI configuration:

return [
    'yii3/debug' => [
        'collectors' => [
            \App\Debug\ExampleCollector::class,
        ],
        'panels' => [
            \App\Debug\ExamplePanel::class,
        ],
    ],
];

For example, both classes may return app.example from id(). Package DI converts these explicit class lists to container references and retains the built-in request collector and panel. Stored payloads without a registered panel remain inspectable through the escaped JSON fallback.

Panels that need the current tag, query parameters, theme, or adapter-generated URLs may additionally implement Yii3\Debug\Panel\ContextAwarePanelInterface. The renderer then calls renderWithContext() with a PHPForge\Debug\Panel\PanelRenderContext; the original PanelInterface::render() contract remains available as the context-free fallback and existing panels require no changes.

Architecture

• php-forge/debug-core owns collector contracts and coordination, failure isolation, strict snapshot hydration, JSON persistence, the request manifest, shared filter and pagination contracts, panel render context, frontend primitives, and portable toolbar data contracts.
• yii3/debug owns PSR-7 request collection, Yii3 DI and middleware lifecycle wiring, optional panel renderers, routes, actions, URL mapping, asset publication, and response injection.
• The adapter resolves shared templates through @yii3DebugViews and renders them with Yiisoft\View\WebView; Core does not register framework assets or render framework responses.

License

The package is released under the BSD-3-Clause license. See LICENSE.