improve output option by introducing Reporter extension

CHANGELOG-6.x.md

@@ -7,6 +7,10 @@ using the [Keep a CHANGELOG](http://keepachangelog.com) principles.
 
 ## [Unreleased]
 
+### Added
+
+- improves `output` option by introducing Reporter extension (see [documentation](docs/01_Components/04_Extensions/Reporter.md))
+
 ## [6.0.1] - 2021-12-13
 
 ### Fixed

docs/01_Components/04_Extensions/Reporter.md

@@ -0,0 +1,43 @@
+<!-- markdownlint-disable MD013 -->
+# Output format
+
+**Since version 6.1.0**, PHP CompatInfo supports different output formats through various formatters.
+
+You can pass the following keywords to the `--output` CLI option of the `analyser:run` command
+in order to affect the output:
+
+- `console`: default table format for human reading.
+- `dump`: raw format (`var_dump`) for debugging purpose only.
+- `json`: creates minified json file format output without whitespaces.
+
+You can also implement your own custom formatter by implementing
+the `Bartlett\CompatInfo\Application\Extension\Reporter\FormatterInterface` interface in a new class.
+
+This is how the `FormatterInterface` interface looks like:
+
+```php
+<?php declare(strict_types=1);
+
+namespace Bartlett\CompatInfo\Application\Extension\Reporter;
+
+interface FormatterInterface
+{
+    /**
+     * @param object $object
+     * @param string[] $formats
+     * @return bool
+     */
+    public function supportsFormatting(object $object, array $formats): bool;
+
+    /**
+     * @param mixed $data Data to format
+     * @return void
+     */
+    public function format($data): void;
+}
+```
+
+Before you can start using your custom output formatter, you have to include it in a new class that implement
+the `Bartlett\CompatInfo\Application\Extension\ExtensionInterface` interface (see [Registering Extensions](Hooks.md) chapter for details).
+
+`ConsoleReporter` is a good first example to follow.

src/Application/Extension/Reporter.php

@@ -0,0 +1,59 @@
+<?php declare(strict_types=1);
+
+namespace Bartlett\CompatInfo\Application\Extension;
+
+use Bartlett\CompatInfo\Application\Event\AfterAnalysisEvent;
+use Bartlett\CompatInfo\Application\Event\AfterAnalysisInterface;
+use Bartlett\CompatInfo\Application\Profiler\Profile;
+
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+use function in_array;
+
+/**
+ * @author Laurent Laville
+ * @since Release 6.1.0
+ */
+abstract class Reporter implements ExtensionInterface, AfterAnalysisInterface
+{
+    protected const NAME = 'custom';
+
+    /** @var InputInterface  */
+    protected $input;
+
+    /** @var OutputInterface  */
+    protected $output;
+
+    public function __construct(InputInterface $input, OutputInterface $output)
+    {
+        $this->input = $input;
+        $this->output = $output;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getName(): string
+    {
+        return static::NAME . '_reporter';
+    }
+
+    /**
+     * @param string[] $formats
+     */
+    public function supportsFormatting(object $object, array $formats): bool
+    {
+        return ($object instanceof Profile && in_array(static::NAME, $formats));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function afterAnalysis(AfterAnalysisEvent $event): void
+    {
+        if ($event->hasArgument('profile')) {
+            $this->format($event->getArgument('profile'));  // @phpstan-ignore-line
+        }
+    }
+}