README.md

Debug Extension for Yii

This extension provides a debugger for Yii framework applications. When this extension is used, a debugger toolbar will appear at the bottom of every page. The extension also provides a set of standalone pages to display more detailed debug information.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

composer require yiisoft/yii-debug --dev

The debug extension also can be installed without the --dev flag if you want to collect data in production. Specify needed collectors only to reduce functions overriding and improve performance.

Usage

Once the extension is installed, modify your config/common/params.php as follows:

return [
    'yiisoft/yii-debug' => [
        'enabled' => true,
    ],
    // ...
];

All included collectors start listen and collect payloads from each HTTP request or console run.

Install both yiisoft/yii-debug-api and yiisoft/yii-dev-panel to be able to interact with collected data through UI.

Logging

If you use FileStorage, specify the filesystem path where collected data will be stored by adding the following lines into the configuration:

return [
    'yiisoft/yii-debug' => [
        // It's default path to store collected payload
        // @runtime = @root/runtime
        'path' => '@runtime/debug',
    ],
    // ...
];

Filtering

Disabling debugging for certain requests or console runs may help you to debug in production or not to flood the debug storage with unuseful payloads.

You can specify which routes should not trigger the Debug extension by adding the ones into the configuration:

return [
    'yiisoft/yii-debug' => [
        'ignoredRequests' => [
            '/assets/**',
        ],
    ],
    // ...
];

See (\Yiisoft\Strings\WildcardPattern)[https://github.com/yiisoft/strings#wildcardpattern-usage] for more details about the pattern syntax.

In order to disable debugging certain console commands you can also specify them via ignoredCommands. Here is default ignored command list:

return [
    'yiisoft/yii-debug' => [
        'ignoredCommands' => [
            'completion',
            'help',
            'list',
            'serve',
            'debug/reset',
        ],
    ],
    // ...
];

Collectors

Yii Debug uses a concept named "collectors". Each collector decides what payload it needs to collect and exports the collected payload in order to save it into storage.

A collector may work either both with HTTP requests and console runs, or individually. A collector may be either an event listener or a decorator to any service defined in the application DI container configuration.

Take a look at the Yiisoft\Yii\Debug\Collector\CollectorInterface:

namespace Yiisoft\Yii\Debug\Collector;

interface CollectorInterface
{
    /**
     * @return string Collector's name.
     */
    public function getName(): string;

    /**
     * Called once at application startup.
     * Any initialization could be done here.
     */
    public function startup(): void;

    /**
     * Called once at application shutdown.
     * Cleanup could be done here.
     */
    public function shutdown(): void;

    /**
     * @return array Data collected.
     */
    public function getCollected(): array;
}

Use the trait to reduce the duplication of code and any possible bugs: \Yiisoft\Yii\Debug\Collector\CollectorTrait

All you need to create a collector is to implement the interface and register it in the configuration.

Example

class MyCollector implements \Yiisoft\Yii\Debug\Collector\CollectorInterface
{
    use \Yiisoft\Yii\Debug\Collector\CollectorTrait;
    
    /**
     * Payload collected during a run. 
     */
    private array $data = [];

    public function getCollected() : array
    {
        return $this->data;
    }
}

When you implement collecting payload, it is also a good idea to implement data reset. With CollectorTrait it is as simple as adding reset method:

    private function reset(): void
    {
        $this->data = [];
    }

You can enable collector in application configuration as follows:

return [
    'yiisoft/yii-debug' => [
        // if you want to register collector both for web requests and console runs
        'collectors' => [
            \App\Debug\AwesomeCollector::class,
        ],
        // if you want to register collector only for web requests
        'collectors.web' => [
            \App\Debug\AwesomeWebCollector::class,
        ],
        // if you want to register collector only for console runs
        'collectors.console' => [
            \App\Debug\AwesomeConsoleCollector::class,
        ],
    ],
];

Under yiisoft/yii-debug configuration you may use:

1. collectors key for both web and console runs
2. collectors.web key only for web requests
3. collectors.console key only for console runs

Do not register a collector for a session where the collector will not collect any payload.

The lines above connect collectors with a debug extension run. Under the hood it calls getCollected() method from the collectors at the end of application cycle run.

Event listener collector

Subscribe to any events you want with adding a listener into the configuration:

With yiisoft/event-dispatcher configuration it may look like the following:

return [
    \Yiisoft\Yii\Http\Event\BeforeRequest::class => [
        [\App\Debug\AwesomeCollector::class, 'collect'],
    ],
];

Each Yiisoft\Yii\Http\Event\BeforeRequest triggered event will call App\Debug\AwesomeCollector::collect($event) method, so you can collect any data from the event or call any other services to enrich the event data with additional payload.

Proxy collector

Proxy collectors are used in case you want to decorate a service from DI container and sniff methods' calls with its values.

First you need to create a class that will work as a decorator. See https://en.wikipedia.org/wiki/Decorator_pattern if you are new with it.

Decorators may inject any services through __construct method, but you should specify services you like to wrap. In the section trackedServices of yiisoft/yii-debug configuration you should specify:

1. A service you want to decorate
2. A decorator that will decorate the service
3. A collector that will be injected into the decorator

Syntax of configuration is: Decorating service => [Decorator, Collector].

Despite adding the tracking service configuration you still need to register the collector if you did not do it before. Whole configuration of added proxy collector looks like the following:

return [
    'yiisoft/yii-debug' => [
        'collectors' => [
            \App\Debug\AwesomeCollector::class,
        ],
        'trackedServices' => [
            // Decorating service => [Decorator, Collector],
            \Psr\Log\LoggerInterface::class => [\App\Debug\LoggerInterfaceProxy::class, \App\Debug\AwesomeCollector::class],
        ],
    ],
];

Summary collector

Summary collector is a collector that provides additional "summary" payload. The summary payload is used to reduce time to read usual payload and summarise some metrics to get better UX.

Summary collector is usual collector with the additional method getSummary(). Take a look at the \Yiisoft\Yii\Debug\Collector\SummaryCollectorInterface:

namespace Yiisoft\Yii\Debug\Collector;

/**
 * Summary data collector responsibility is to collect summary data for a collector.
 * Summary is used to display a list of previous requests and select one to display full info.
 * Its data set is specific to the list and is reduced compared to full data collected
 * in {@see CollectorInterface}.
 */
interface SummaryCollectorInterface extends CollectorInterface
{
    /**
     * @return array Summary payload. Keys may cross with any other summary collectors.
     */
    public function getSummary(): array;
}

We suggest you to give short names to your summary payload to be able to read the keys and decide to use them or not.

    // with getCollected you can inspect all collected payload
    public function getCollected(): array
    {
        return $this->requests;
    }

    // getSummary gives you short description of the collected data just to decide inspect it deeper or not
    public function getSummary(): array
    {
        return [
            'web' => [
                'totalRequests' => count($this->requests),
            ],
        ];
    }

ServiceCollector

ServiceCollector is a collector that listens all tracked services and collects its arguments, results and errors.

By default, the debug extension has enabled \Yiisoft\Yii\Debug\Collector\ServiceCollector with the following settings:

1. Log arguments
2. Log results
3. Log errors

It may degrade the application performance so it may be a good idea to disable it in production.

You may control what is logged by specifying the settings in the configuration:

use Yiisoft\Yii\Debug\Collector\ContainerInterfaceProxy;

return [
    'yiisoft/yii-debug' => [
        // use 0 or ContainerInterfaceProxy::LOG_NOTHING to disable logging
        'logLevel' => ContainerInterfaceProxy::LOG_ARGUMENTS | ContainerInterfaceProxy::LOG_RESULT | ContainerInterfaceProxy::LOG_ERROR,
    ],
];

Console commands

debug/reset

The debug/reset command cleans all collected data. It's similar to rm -rf runtime/debug if you use file storage, but may be also useful if you use another storage driver.

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

Support the project

Follow updates

License

The Debug Extension for Yii is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.