Skip to content

Commit

Permalink
Restructure documentation (#233)
Browse files Browse the repository at this point in the history 
* Restructure documentation

---------

Co-authored-by: Alexander Makarov <[email protected]>
  • Loading branch information
@xepozz @samdark
xepozz and samdark authored Jan 6, 2024
1 parent 8b0585a commit 5b1263c
Show file tree
Hide file tree
Showing 12 changed files with 659 additions and 279 deletions.
279 changes: 2 additions & 277 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,284 +52,9 @@ All included collectors start listen and collect payloads from each HTTP request
Install both [`yiisoft/yii-debug-api`](https://github.com/yiisoft/yii-debug-api) and [`yiisoft/yii-dev-panel`](https://github.com/yiisoft/yii-dev-panel)
to be able to interact with collected data through UI.

## Logging
### Documentation

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

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

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

```php
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`](./src/Collector/CollectorInterface.php):

```php
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`](./src/Collector/CollectorTrait.php)

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

### Example

```php
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:
```php
private function reset(): void
{
$this->data = [];
}
```

You can enable collector in application configuration as follows:

```php
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`](https://github.com/yiisoft/event-dispatcher) configuration it may look like the following:

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

```php
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`](./src/Collector/SummaryCollectorInterface.php):

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

```php
// 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`](./src/Collector/ServiceCollector.php) 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:

```php
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.
[English](docs/en/index.md)

### Unit testing

Expand Down
Loading

0 comments on commit 5b1263c

Please sign in to comment.