diff --git a/README.md b/README.md index ef1f39c9..331d06a8 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/en/collector.md b/docs/en/collector.md new file mode 100644 index 00000000..ebc3036f --- /dev/null +++ b/docs/en/collector.md @@ -0,0 +1,152 @@ +# Collector + +## 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], + ], + ], +]; +``` diff --git a/docs/en/collector/service.md b/docs/en/collector/service.md new file mode 100644 index 00000000..f1376535 --- /dev/null +++ b/docs/en/collector/service.md @@ -0,0 +1,25 @@ +# Collectors + +## Service collector + +`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, + ], +]; +``` diff --git a/docs/en/collector/summary.md b/docs/en/collector/summary.md new file mode 100644 index 00000000..fcf5a1b6 --- /dev/null +++ b/docs/en/collector/summary.md @@ -0,0 +1,49 @@ +# Collectors + +Read more about collectors in the [Collector](../collector.md) section. + +## 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), + ], + ]; + } +``` diff --git a/docs/en/command-container.md b/docs/en/command-container.md new file mode 100644 index 00000000..57dc3aeb --- /dev/null +++ b/docs/en/command-container.md @@ -0,0 +1,217 @@ +# Console commands + +## `debug:container` + +The `debug/container` command displays all registered services and config groups. + +For example: + +``` +❯ ./yii debug:container ++---------------------- params-console -----------------------+ +| Group | Services | ++------------------------------+------------------------------+ +| yiisoft/yii-console | yiisoft/yii-console | +| yiisoft/yii-event | yiisoft/yii-event | +| yiisoft/cache-file | yiisoft/cache-file | +| yiisoft/mailer | yiisoft/mailer | +| symfony/mailer | symfony/mailer | +| yiisoft/rbac-rules-container | yiisoft/rbac-rules-container | +| yiisoft/router-fastroute | yiisoft/router-fastroute | +| yiisoft/user | yiisoft/user | +| yiisoft/yii-cycle | yiisoft/yii-cycle | +| yiisoft/yii-dataview | yiisoft/yii-dataview | +| yiisoft/yii-debug | yiisoft/yii-debug | +| yiisoft/yii-debug-api | yiisoft/yii-debug-api | +| yiisoft/yii-swagger | yiisoft/yii-swagger | +| yiisoft/yii-sentry | yiisoft/yii-sentry | +| yiisoft/yii-debug-viewer | yiisoft/yii-debug-viewer | +| yiisoft/yii-gii | yiisoft/yii-gii | +| yiisoft/assets | yiisoft/assets | +| yiisoft/form | yiisoft/form | +| yiisoft/log-target-file | yiisoft/log-target-file | +| yiisoft/profiler | yiisoft/profiler | +| yiisoft/yii-view | yiisoft/yii-view | +| yiisoft/aliases | yiisoft/aliases | +| yiisoft/csrf | yiisoft/csrf | +| yiisoft/session | yiisoft/session | +| yiisoft/data-response | yiisoft/data-response | +| yiisoft/widget | yiisoft/widget | +| yiisoft/validator | yiisoft/validator | +| yiisoft/view | yiisoft/view | +| yiisoft/translator | yiisoft/translator | +| mailer | mailer | +| yiisoft/cookies | yiisoft/cookies | ++------------------------------+------------------------------+ ++- bootstrap-c... -+ +| Group | Services | ++-------+----------+ +| 0 | Closure | +| 1 | Closure | +| 2 | Closure | +| 3 | Closure | ++-------+----------+ ++-------------------------------------------------------------------------------- di-console ---------------------------------------------------------------------------------+ +| Group | Services | ++--------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| Cycle\Migrations\Migrator | Yiisoft\Yii\Cycle\Factory\MigratorFactory | +| Cycle\Migrations\Config\MigrationConfig | Yiisoft\Yii\Cycle\Factory\MigrationConfigFactory | +| Yiisoft\Yii\Cycle\Command\CycleDependencyProxy | Closure | +| Yiisoft\TranslatorExtractor\Extractor | Yiisoft\TranslatorExtractor\Extractor | +| Symfony\Component\Console\CommandLoader\CommandLoaderInterface | Yiisoft\Yii\Console\CommandLoader | +| Yiisoft\Yii\Console\Command\Serve | Yiisoft\Yii\Console\Command\Serve | +| Yiisoft\Yii\Console\Application | Yiisoft\Yii\Console\Application | +| Yiisoft\Yii\Debug\Debugger | Yiisoft\Yii\Debug\Debugger | +| Yiisoft\EventDispatcher\Provider\ListenerCollection | Closure | +| Yiisoft\Cache\File\FileCache | Closure | +| Yiisoft\FormModel\FormHydrator | Yiisoft\FormModel\FormHydrator | +| Yiisoft\Mailer\MessageBodyRenderer | Yiisoft\Mailer\MessageBodyRenderer | +| Yiisoft\Mailer\MessageFactoryInterface | Yiisoft\Mailer\MessageFactory | +| Symfony\Component\Mailer\Transport\TransportInterface | Closure | +| Yiisoft\Mailer\FileMailer | Yiisoft\Mailer\FileMailer | +| Yiisoft\Mailer\MailerInterface | Yiisoft\Mailer\FileMailer | +| Yiisoft\Rbac\RuleFactoryInterface | Yiisoft\Rbac\Rules\Container\RulesContainer | +| Yiisoft\Router\UrlGeneratorInterface | Yiisoft\Router\FastRoute\UrlGenerator | +| Cycle\Database\DatabaseProviderInterface | Yiisoft\Definitions\Reference | +| Cycle\Database\DatabaseManager | Yiisoft\Yii\Cycle\Factory\DbalFactory | +| Cycle\ORM\ORMInterface | Yiisoft\Definitions\Reference | +| Cycle\ORM\ORM | Closure | +| Cycle\ORM\EntityManagerInterface | Yiisoft\Definitions\Reference | +| Cycle\ORM\EntityManager | Cycle\ORM\EntityManager | +| Spiral\Core\FactoryInterface | Yiisoft\Definitions\Reference | +| Cycle\ORM\FactoryInterface | Closure | +| Cycle\ORM\SchemaInterface | Closure | +| Yiisoft\Yii\Cycle\Schema\SchemaProviderInterface | Closure | +| Yiisoft\Yii\Cycle\Schema\SchemaConveyorInterface | Closure | +| yii.dataview.categorySource | yii.dataview.categorySource | +| Sentry\Transport\TransportFactoryInterface | Sentry\Transport\DefaultTransportFactory | +| Sentry\HttpClient\HttpClientFactoryInterface | Sentry\HttpClient\HttpClientFactory | +| Sentry\Options | Sentry\Options | +| Sentry\State\HubInterface | Sentry\State\Hub | +| Yiisoft\Yii\Gii\GiiInterface | Closure | +| Yiisoft\Yii\Gii\ParametersProvider | Yiisoft\Yii\Gii\ParametersProvider | +| Yiisoft\Log\Target\File\FileRotatorInterface | Yiisoft\Log\Target\File\FileRotator | +| Yiisoft\Log\Target\File\FileTarget | Closure | +| Yiisoft\Yii\Debug\Collector\ContainerProxyConfig | Closure | +| Yiisoft\Yii\Debug\Collector\Stream\FilesystemStreamCollector | Yiisoft\Yii\Debug\Collector\Stream\FilesystemStreamCollector | +| Yiisoft\Yii\Debug\Storage\StorageInterface | Closure | +| Yiisoft\Profiler\ProfilerInterface | Closure | +| Yiisoft\Profiler\Target\LogTarget | Yiisoft\Profiler\Target\LogTarget | +| Yiisoft\Profiler\Target\FileTarget | Yiisoft\Profiler\Target\FileTarget | +| Yiisoft\Aliases\Aliases | Yiisoft\Aliases\Aliases | +| Yiisoft\Cache\CacheInterface | Yiisoft\Cache\Cache | +| Psr\SimpleCache\CacheInterface | Yiisoft\Cache\File\FileCache | +| Yiisoft\Hydrator\HydratorInterface | Yiisoft\Hydrator\Hydrator | +| Yiisoft\Validator\ValidatorInterface | Yiisoft\Validator\Validator | +| Yiisoft\Validator\RuleHandlerResolverInterface | Yiisoft\Validator\RuleHandlerResolver\RuleHandlerContainer | +| yii.validator.categorySource | yii.validator.categorySource | +| Yiisoft\View\View | Yiisoft\View\View | +| Yiisoft\Router\RouteCollectorInterface | Yiisoft\Router\RouteCollector | +| Yiisoft\Router\CurrentRoute | Yiisoft\Router\CurrentRoute | +| Psr\EventDispatcher\EventDispatcherInterface | Yiisoft\EventDispatcher\Dispatcher\Dispatcher | +| Psr\EventDispatcher\ListenerProviderInterface | Yiisoft\EventDispatcher\Provider\Provider | +| Yiisoft\Translator\TranslatorInterface | Yiisoft\Translator\Translator | +| Yiisoft\Hydrator\AttributeHandling\ResolverFactory\AttributeResolverFactoryInterface | Yiisoft\Hydrator\AttributeHandling\ResolverFactory\ContainerAttributeResolverFactory | +| Yiisoft\Hydrator\ObjectFactory\ObjectFactoryInterface | Yiisoft\Hydrator\ObjectFactory\ContainerObjectFactory | +| Psr\Log\LoggerInterface | Yiisoft\Log\Logger | +| Psr\Http\Message\RequestFactoryInterface | HttpSoft\Message\RequestFactory | +| Psr\Http\Message\ServerRequestFactoryInterface | HttpSoft\Message\ServerRequestFactory | +| Psr\Http\Message\ResponseFactoryInterface | HttpSoft\Message\ResponseFactory | +| Psr\Http\Message\StreamFactoryInterface | HttpSoft\Message\StreamFactory | +| Psr\Http\Message\UriFactoryInterface | HttpSoft\Message\UriFactory | +| Psr\Http\Message\UploadedFileFactoryInterface | HttpSoft\Message\UploadedFileFactory | +| Yiisoft\Rbac\ItemsStorageInterface | Yiisoft\Rbac\Php\ItemsStorage | +| Yiisoft\Rbac\AssignmentsStorageInterface | Yiisoft\Rbac\Php\AssignmentsStorage | +| Yiisoft\Access\AccessCheckerInterface | Yiisoft\Rbac\Manager | +| Yiisoft\Router\RouteCollectionInterface | Closure | +| Http\Client\HttpClient | GuzzleHttp\Client | +| Http\Client\HttpAsyncClient | Http\Adapter\Guzzle7\Client | +| translation.app | translation.app | ++--------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ ++----------------------- di-providers-console ------------------------+ +| Group | Services | ++----------------------------+----------------------------------------+ +| yiisoft/yii-debug/Debugger | Yiisoft\Yii\Debug\ProxyServiceProvider | ++----------------------------+----------------------------------------+ ++- di-delegate... -+ +| Group | Services | ++-------+----------+ +| 0 | Closure | ++-------+----------+ ++----------------------------------------------- events-console ------------------------------------------------+ +| Group | Services | ++-------------------------------------------------------+-------------------------------------------------------+ +| Yiisoft\Yii\Console\Event\ApplicationStartup | Yiisoft\Yii\Console\Event\ApplicationStartup | +| Yiisoft\Yii\Console\Event\ApplicationShutdown | Yiisoft\Yii\Console\Event\ApplicationShutdown | +| Symfony\Component\Console\Event\ConsoleCommandEvent | Symfony\Component\Console\Event\ConsoleCommandEvent | +| Symfony\Component\Console\Event\ConsoleErrorEvent | Symfony\Component\Console\Event\ConsoleErrorEvent | +| Symfony\Component\Console\Event\ConsoleTerminateEvent | Symfony\Component\Console\Event\ConsoleTerminateEvent | +| Yiisoft\Yii\Cycle\Event\AfterMigrate | Yiisoft\Yii\Cycle\Event\AfterMigrate | ++-------------------------------------------------------+-------------------------------------------------------+ ++---- widgets -----+ +| Group | Services | ++-------+----------+ ++---- widgets-themes -----+ +| Group | Services | ++------------+------------+ +| bootstrap5 | bootstrap5 | ++------------+------------+ +``` + +### Inspect a service + +You can inspect a service by specifying its name as an argument: + +``` +❯ ./yii debug:container "Psr\Http\Message\UriFactoryInterface" + +Psr\Http\Message\UriFactoryInterface +==================================== + +Psr\Http\Message\UriFactoryInterface +Yiisoft\Definitions\Reference#8425 +( + [Yiisoft\Definitions\Reference:id] => 'HttpSoft\\Message\\UriFactory' + [Yiisoft\Definitions\Reference:optional] => false +) +``` + +> Note: make sure you use quotes if the service name contains a backslash. + +### Inspect a config group + +You can inspect a config group by specifying `--group $name` option: + +``` +❯ ./yii debug:container --group events-console ++----------------------------------------------- events-console ------------------------------------------------+ +| Service | Definition | ++-------------------------------------------------------+-------------------------------------------------------+ +| Symfony\Component\Console\Event\ConsoleCommandEvent | Symfony\Component\Console\Event\ConsoleCommandEvent | +| Symfony\Component\Console\Event\ConsoleErrorEvent | Symfony\Component\Console\Event\ConsoleErrorEvent | +| Symfony\Component\Console\Event\ConsoleTerminateEvent | Symfony\Component\Console\Event\ConsoleTerminateEvent | +| Yiisoft\Yii\Console\Event\ApplicationShutdown | Yiisoft\Yii\Console\Event\ApplicationShutdown | +| Yiisoft\Yii\Console\Event\ApplicationStartup | Yiisoft\Yii\Console\Event\ApplicationStartup | +| Yiisoft\Yii\Cycle\Event\AfterMigrate | Yiisoft\Yii\Cycle\Event\AfterMigrate | ++-------------------------------------------------------+-------------------------------------------------------+ +``` + +### List all groups + +You can list all groups by specifying `--groups` option: + +``` +❯ ./yii debug:container --groups + ---------------------- + Groups + ---------------------- + params-console + bootstrap-console + di-console + di-providers-console + di-delegates-console + events-console + widgets + widgets-themes + ---------------------- +``` diff --git a/docs/en/command-events.md b/docs/en/command-events.md new file mode 100644 index 00000000..088b22a1 --- /dev/null +++ b/docs/en/command-events.md @@ -0,0 +1,142 @@ +# Console commands + +## `debug:events` + +The `debug/events` command displays all registered events and their listeners. + +For example: + +``` +❯ ./yii debug:events ++-------------------------------------------------------+-------+----------------------------------------------------------------------+ +| Event | Count | Listeners | ++-------------------------------------------------------+-------+----------------------------------------------------------------------+ +| Yiisoft\Yii\Console\Event\ApplicationStartup | 3 | static fn (\App\Timer $timer) => $timer->start('overall') | +| | | Yiisoft\Yii\Debug\Debugger::startup | +| | | Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector::collect | +| Yiisoft\Yii\Console\Event\ApplicationShutdown | 2 | Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector::collect | +| | | Yiisoft\Yii\Debug\Debugger::shutdown | +| Symfony\Component\Console\Event\ConsoleCommandEvent | 2 | Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector::collect | +| | | Yiisoft\Yii\Debug\Collector\Console\CommandCollector::collect | +| Symfony\Component\Console\Event\ConsoleErrorEvent | 3 | Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector::collect | +| | | Yiisoft\Yii\Debug\Collector\Console\CommandCollector::collect | +| | | Yiisoft\Yii\Console\ErrorListener::onError | +| Symfony\Component\Console\Event\ConsoleTerminateEvent | 3 | Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector::collect | +| | | Yiisoft\Yii\Debug\Collector\Console\CommandCollector::collect | +| | | static function (\Psr\Log\LoggerInterface $logger): void { | +| | | if ($logger instanceof \Yiisoft\Log\Logger) { | +| | | $logger->flush(true); | +| | | } | +| | | } | +| Yiisoft\Yii\Cycle\Event\AfterMigrate | 1 | Yiisoft\Yii\Cycle\Listener\MigrationListener::onAfterMigrate | ++-------------------------------------------------------+-------+----------------------------------------------------------------------+ +``` +### List all groups + +You can list all groups by specifying `--groups` option: + +``` +❯ ./yii debug:events --groups + ---------------------- + Groups + ---------------------- + params-console + bootstrap-console + di-console + di-providers-console + di-delegates-console + events-console + widgets + widgets-themes + ---------------------- +``` + +> Note: unfortunately, the command cannot recognize only event groups automatically, so you will have all groups listed. + +### Inspect a group + +You can inspect a group by specifying its name as an argument: + +``` +❯ ./yii debug:events --group events-console + +Symfony\Component\Console\Event\ConsoleCommandEvent +=================================================== + +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector" + 1 => "collect" +] +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\CommandCollector" + 1 => "collect" +] + +Symfony\Component\Console\Event\ConsoleErrorEvent +================================================= + +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector" + 1 => "collect" +] +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\CommandCollector" + 1 => "collect" +] +array:2 [ + 0 => "Yiisoft\Yii\Console\ErrorListener" + 1 => "onError" +] + +Symfony\Component\Console\Event\ConsoleTerminateEvent +===================================================== + +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector" + 1 => "collect" +] +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\CommandCollector" + 1 => "collect" +] +""" +static function (\Psr\Log\LoggerInterface $logger): void {\n + if ($logger instanceof \Yiisoft\Log\Logger) {\n + $logger->flush(true);\n + }\n +} +""" + +Yiisoft\Yii\Console\Event\ApplicationShutdown +============================================= + +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector" + 1 => "collect" +] +array:2 [ + 0 => "Yiisoft\Yii\Debug\Debugger" + 1 => "shutdown" +] + +Yiisoft\Yii\Console\Event\ApplicationStartup +============================================ + +"static fn (\App\Timer $timer) => $timer->start('overall')" +array:2 [ + 0 => "Yiisoft\Yii\Debug\Debugger" + 1 => "startup" +] +array:2 [ + 0 => "Yiisoft\Yii\Debug\Collector\Console\ConsoleAppInfoCollector" + 1 => "collect" +] + +Yiisoft\Yii\Cycle\Event\AfterMigrate +==================================== + +array:2 [ + 0 => "Yiisoft\Yii\Cycle\Listener\MigrationListener" + 1 => "onAfterMigrate" +] +``` diff --git a/docs/en/command-reset.md b/docs/en/command-reset.md new file mode 100644 index 00000000..c94137b7 --- /dev/null +++ b/docs/en/command-reset.md @@ -0,0 +1,6 @@ +# 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. diff --git a/docs/en/filtering.md b/docs/en/filtering.md new file mode 100644 index 00000000..40986f63 --- /dev/null +++ b/docs/en/filtering.md @@ -0,0 +1,36 @@ +# Filtering + +Disabling debugging for certain requests or console commands may help you to debug in production or not to flood the debug storage with useful 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', + ], + ], + // ... +]; +``` diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 00000000..143b5cbd --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,11 @@ +# Documentation + +## Collectors +- [Main concept](./collector.md) +- [Summary collectors](./collector/summary.md) +- [Service Collector](./collector/service.md) + +## Console commands +- [`debug:reset`](./command-reset.md) +- [`debug:container`](./command-container.md) +- [`debug:events`](./command-events.md) diff --git a/docs/en/logging.md b/docs/en/logging.md new file mode 100644 index 00000000..1b38b8cb --- /dev/null +++ b/docs/en/logging.md @@ -0,0 +1,26 @@ +# Logging + +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', + ], + // ... +]; +``` + +## Driver + +You can specify the storage driver by adding the following lines into the `di` configuration: + +```php +return [ + \Yiisoft\Yii\Debug\Storage\StorageInterface::class => \Yiisoft\Yii\Debug\Storage\FileStorage::class, +]; +``` + +> Note: Currently, only `FileStorage` and `MemoryStorage` are supported. diff --git a/src/Command/DebugContainerCommand.php b/src/Command/DebugContainerCommand.php index 15baa001..63f63f90 100644 --- a/src/Command/DebugContainerCommand.php +++ b/src/Command/DebugContainerCommand.php @@ -118,7 +118,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int $groups = array_keys($build); ksort($groups); - $io->table(['Group'], array_map(fn ($group) => [$group], $groups)); + $io->table(['Groups'], array_map(fn ($group) => [$group], $groups)); return ExitCode::OK; } diff --git a/src/Command/DebugEventsCommand.php b/src/Command/DebugEventsCommand.php index 1aba6e10..c9a338c5 100644 --- a/src/Command/DebugEventsCommand.php +++ b/src/Command/DebugEventsCommand.php @@ -51,7 +51,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int $groups = array_keys($build); ksort($groups); - $io->table(['Group'], array_map(fn ($group) => [$group], $groups)); + $io->table(['Groups'], array_map(fn ($group) => [$group], $groups)); return ExitCode::OK; }