#279 - Mark the classes not meant to be extended @final and the infrastructure classes @internal

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#279](https://github.com/cleverage/process-bundle/issues/279) Define the public API (Symfony BC promise): the classes not meant to be extended are marked `@final since 5.4` (the engine: `ProcessManager`, `ProcessConfigurationRegistry`, `TransformerRegistry`, `ContextualOptionResolver`; the models: `ProcessState`, `ProcessHistory`, `SubprocessInstance`, the configurations, the events, the `Filesystem` files; the concrete tasks and transformers), they will be `final` in v6.0: extending them triggers a deprecation with the Symfony `DebugClassLoader`. The abstract classes, interfaces, traits, exceptions and the file tasks extended by other tasks (`FileReaderTask`, `LineReaderTask`, `FolderBrowserTask`, `CsvReaderTask`, `InputCsvReaderTask`, `Filesystem\CsvResource`) stay open. `TaskRegistry`, new in this version, is `final`. The infrastructure classes are marked `@internal`: `CleverAgeProcessExtension`, `Configuration`, the commands, `DataQueueEventListener`, `PhpFunctionProvider`, the Monolog processors, `ProcessLogger` and `TaskLogger`. Update documentation.
 * [#269](https://github.com/cleverage/process-bundle/issues/269) Composer: `symfony/process`, `symfony/stopwatch`, `symfony/var-dumper` and `symfony/monolog-bundle` are no longer required, they are suggested (applications using them must require them). Without `symfony/process` (`CommandRunnerTask`, `ProcessLauncherTask`) or `symfony/stopwatch` (`StopwatchTask`), the container still compiles and these tasks fail with an explicit message (`UnavailableServicesCompilerPass`); without `symfony/var-dumper`, nothing is dumped (as before); without `symfony/monolog-bundle`, the `cleverage_process*` channels and processors are not registered and the default logger is used. `monolog/monolog` stays required (`Logger\*Processor`). Remove the unused `symfony/monolog-bridge` dependency. `ProcessConfiguration` no longer uses `array_any()` (PHP 8.4), whose polyfill was only installed by the removed packages. Add a `conflict` with `cleverage/doctrine-process-bundle`, `cleverage/soap-process-bundle` and `cleverage/ui-process-bundle` `<3.3`, which use the MonologBundle without requiring it. Update documentation, add tests.
 * [#91](https://github.com/cleverage/process-bundle/issues/91) Reference a task by a code in the process configurations: new `task` key (`task: transformer`), next to its `options`. The code of a task service is declared with the new `code` attribute of the `cleverage.task` tag or the new `#[AsTask(code: '...')]` attribute (autoconfiguration); every task of the bundle has a code, given on its reference page (snake case of its class name without `Task`, e.g. `transformer`, `constant_output`, `csv_reader`). The codes are resolved when the container is compiled (`TaskLocatorCompilerPass`): an unknown or duplicate code fails the compilation. Referencing a task by its `service` (e.g. `service: '@CleverAge\ProcessBundle\Task\TransformerTask'`) is deprecated (configuration deprecation), it will be removed in v6.0: use `task: <code>`. The documentation examples use the codes. Update documentation, add tests.
 * [#276](https://github.com/cleverage/process-bundle/issues/276) TransformerRegistry: the transformers are loaded lazily from a service locator indexed by code (new internal `TransformerLocatorCompilerPass`, new optional `TransformerRegistry` constructor argument): a transformer is only instantiated when a process uses it. The code is given by the new `code` attribute of the `cleverage.transformer` tag, or by the new `#[AsTransformer(code: '...')]` attribute (autoconfiguration); it must be the one returned by `getCode()`. All the bundle transformers and the generic transformers have their code. Duplicate codes fail the container compilation. A transformer tagged without `code` is still registered eagerly, with `TransformerRegistry::addTransformer()`, which is deprecated (the `code` will be required in v6.0, #280). `RegistryCompilerPass` is no longer used and deprecated. `TransformerInterface::getCode()` is deprecated (`@deprecated` PHPDoc: no runtime notice is possible for an interface method), it will be removed from the interface in v6.0 (#280): keep implementing it, returning the code of the tag until then. Update documentation, add tests.

docs/05-good_practices.md

@@ -79,3 +79,25 @@ relying on the order in which branches are executed.
 Values that change between executions (a file name, a date, a limit...) should not be hard-coded in the process
 configuration: pass them as [contextual values](01-quick_start.md#contextual-values) (`-c key:value`) and use
 `{{ key }}` placeholders in the task options.
+
+## Extend the bundle without inheriting its classes
+
+The classes meant to be extended are the abstract ones (`AbstractConfigurableTask`, `AbstractIterableOutputTask`,
+`AbstractCsvTask`, `Logger\AbstractLogger`...), the interfaces and traits, the exceptions, and a few file tasks used as
+a base by other tasks (`FileReaderTask`, `LineReaderTask`, `FolderBrowserTask`, `CsvReaderTask`, `InputCsvReaderTask`
+and `Filesystem\CsvResource`).
+
+The other classes are marked `@final since 5.4`, they will be `final` in v6.0: the engine (`ProcessManager`, the
+registries, `ContextualOptionResolver`), the models (`ProcessState`, the configurations, the events) and the concrete
+tasks and transformers. Extending one of them triggers a deprecation (with the Symfony `DebugClassLoader`, enabled by
+`symfony/error-handler` in debug mode). Instead:
+
+- write your own task (extending `AbstractConfigurableTask`) or transformer, and inject the services of the bundle you
+  need;
+- [decorate](https://symfony.com/doc/current/service_container/service_decoration.html) a service, or listen to the
+  process [events](04-advanced_workflow.md);
+- chain existing tasks and transformers in the process configuration.
+
+The classes marked `@internal` (the dependency injection extension, configuration and compiler passes, the commands, the
+event listeners, the Monolog processors, `ProcessLogger`, `TaskLogger` and `PhpFunctionProvider`) are not part of the
+public API: they can change in any version.

src/Command/ExecuteProcessCommand.php

@@ -30,6 +30,8 @@
 
 /**
  * Run a process from the command line interface.
+ *
+ * @internal
  */
 #[AsCommand(name: 'cleverage:process:execute', description: 'Execute a process', )]
 class ExecuteProcessCommand extends Command

src/Command/ListProcessCommand.php

@@ -23,6 +23,8 @@
 
 /**
  * List all configured processes.
+ *
+ * @internal
  */
 #[AsCommand(name: 'cleverage:process:list', description: 'List defined processes', )]
 class ListProcessCommand extends Command

src/Command/ProcessHelpCommand.php

@@ -34,6 +34,8 @@
 /**
  * Describe a process configuration
  * This is a POC, waiting to evolve properly.
+ *
+ * @internal
  */
 #[AsCommand(name: 'cleverage:process:help', description: 'Describe a process', )]
 class ProcessHelpCommand extends Command

src/Configuration/ProcessConfiguration.php

@@ -19,6 +19,8 @@
 
 /**
  * Holds the processes configuration to launch a task.
+ *
+ * @final since 5.4
  */
 class ProcessConfiguration
 {

src/Configuration/TaskConfiguration.php

@@ -19,6 +19,8 @@
 
 /**
  * Represents a task configuration inside a process.
+ *
+ * @final since 5.4
  */
 class TaskConfiguration
 {

src/Context/ContextualOptionResolver.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\ProcessBundle\Context;
 
+/**
+ * @final since 5.4
+ */
 class ContextualOptionResolver
 {
     /**

src/DependencyInjection/CleverAgeProcessExtension.php

@@ -31,6 +31,8 @@
  * This is the class that loads and manages your bundle configuration.
  *
  * @see https://symfony.com/doc/current/bundles/extension.html
+ *
+ * @internal
  */
 class CleverAgeProcessExtension extends Extension
 {

src/DependencyInjection/Configuration.php

@@ -23,6 +23,8 @@
  * This is the class that validates and merges configuration from your app/config files.
  *
  * @see https://symfony.com/doc/current/bundles/configuration.html
+ *
+ * @internal
  */
 class Configuration implements ConfigurationInterface
 {

src/Event/ConsoleProcessEvent.php

@@ -19,6 +19,8 @@
 
 /**
  * Event object used during CLI process manipulation.
+ *
+ * @final since 5.4
  */
 class ConsoleProcessEvent extends Event
 {

src/Event/EventDispatcherTaskEvent.php

@@ -16,6 +16,9 @@
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Symfony\Contracts\EventDispatcher\Event;
 
+/**
+ * @final since 5.4
+ */
 class EventDispatcherTaskEvent extends Event
 {
     public function __construct(

src/Event/ProcessEvent.php

@@ -17,6 +17,8 @@
 
 /**
  * Event object for process start/stop/fail.
+ *
+ * @final since 5.4
  */
 class ProcessEvent extends Event
 {

src/EventListener/DataQueueEventListener.php

@@ -20,6 +20,8 @@
  * Class DataQueueEventListener
  * This is a basic queue, mainly aiming to catch data coming out of a process
  * Used mostly for testing purpose.
+ *
+ * @internal
  */
 class DataQueueEventListener
 {

src/ExpressionLanguage/PhpFunctionProvider.php

@@ -18,6 +18,8 @@
 
 /**
  * Allow to inject a set of PHP function into an ExpressionLanguage instance.
+ *
+ * @internal
  */
 class PhpFunctionProvider implements ExpressionFunctionProviderInterface
 {

src/Filesystem/CsvFile.php

@@ -15,6 +15,8 @@
 
 /**
  * Read and write CSV files through a simple API.
+ *
+ * @final since 5.4
  */
 class CsvFile extends CsvResource
 {

src/Filesystem/JsonStreamFile.php

@@ -15,6 +15,8 @@
 
 /**
  * Wrapper around JSON files to read them in a stream.
+ *
+ * @final since 5.4
  */
 class JsonStreamFile implements FileStreamInterface, WritableFileInterface
 {

src/Filesystem/SplFile.php

@@ -15,6 +15,8 @@
 
 /**
  * Wrapper around files to read/write them.
+ *
+ * @final since 5.4
  */
 class SplFile
 {

src/Filesystem/XmlFile.php

@@ -15,6 +15,8 @@
 
 /**
  * Read and write XML files.
+ *
+ * @final since 5.4
  */
 class XmlFile
 {

src/Logger/AbstractProcessor.php

@@ -18,6 +18,9 @@
 use CleverAge\ProcessBundle\Model\ProcessHistory;
 use Monolog\LogRecord;
 
+/**
+ * @internal
+ */
 class AbstractProcessor
 {
     public function __construct(

src/Logger/ProcessLogger.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\ProcessBundle\Logger;
 
+/**
+ * @internal
+ */
 class ProcessLogger extends AbstractLogger
 {
 }

src/Logger/ProcessProcessor.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\ProcessBundle\Logger;
 
+/**
+ * @internal
+ */
 class ProcessProcessor extends AbstractProcessor
 {
 }

src/Logger/TaskLogger.php

@@ -13,6 +13,9 @@
 
 namespace CleverAge\ProcessBundle\Logger;
 
+/**
+ * @internal
+ */
 class TaskLogger extends AbstractLogger
 {
 }

src/Logger/TaskProcessor.php

@@ -15,6 +15,9 @@
 
 use Monolog\LogRecord;
 
+/**
+ * @internal
+ */
 class TaskProcessor extends AbstractProcessor
 {
     #[\Override]

src/Logger/TransformerProcessor.php

@@ -15,6 +15,9 @@
 
 use Monolog\LogRecord;
 
+/**
+ * @internal
+ */
 class TransformerProcessor extends AbstractProcessor
 {
     #[\Override]

src/Manager/ProcessManager.php

@@ -38,6 +38,8 @@
 
 /**
  * Execute processes.
+ *
+ * @final since 5.4
  */
 class ProcessManager
 {

src/Model/ProcessHistory.php

@@ -17,6 +17,8 @@
 
 /**
  * Logs information about a process.
+ *
+ * @final since 5.4
  */
 class ProcessHistory implements \Stringable
 {

src/Model/ProcessState.php

@@ -19,6 +19,8 @@
 
 /**
  * Used to pass information between tasks.
+ *
+ * @final since 5.4
  */
 class ProcessState
 {
@@ -298,6 +300,7 @@ public function setContext(array $context): void
     /**
      * @return array<string, mixed>|null
      */
+    // @phpstan-ignore return.unusedType (narrowing the return type of a non-final class breaks the child classes, see #279)
     public function getContextualizedOptions(): ?array
     {
         if (!$this->contextualizedOptions) {

src/Model/SubprocessInstance.php

@@ -19,6 +19,9 @@
 use Symfony\Component\Process\PhpExecutableFinder;
 use Symfony\Component\Process\Process;
 
+/**
+ * @final since 5.4
+ */
 class SubprocessInstance
 {
     final public const OPTION_JSON_BUFFERING = 'json-buffering';

src/Registry/ProcessConfigurationRegistry.php

@@ -21,6 +21,8 @@
 
 /**
  * Build and holds all the process configurations.
+ *
+ * @final since 5.4
  */
 class ProcessConfigurationRegistry
 {

src/Registry/TaskRegistry.php

@@ -24,7 +24,7 @@
  * (see TaskLocatorCompilerPass). The fallback container is only used, with a deprecation, for services that are not
  * in the locator (e.g. a process configuration added at runtime).
  */
-class TaskRegistry
+final class TaskRegistry
 {
     public function __construct(
         protected ContainerInterface $locator,

src/Registry/TransformerRegistry.php

@@ -23,6 +23,8 @@
  * The transformer services are fetched lazily from a service locator indexed by code (`code` attribute of the
  * `cleverage.transformer` tag, or `#[AsTransformer]`, see TransformerLocatorCompilerPass): a transformer is only
  * instantiated when it is used.
+ *
+ * @final since 5.4
  */
 class TransformerRegistry
 {

src/Task/AggregateIterableTask.php

@@ -20,6 +20,8 @@
  * Class AggregateIterableTask.
  *
  * Aggregate the result of iterable tasks in an array
+ *
+ * @final since 5.4
  */
 class AggregateIterableTask implements BlockingTaskInterface
 {

src/Task/ArrayMergeTask.php

@@ -20,6 +20,8 @@
 
 /**
  * Merge every input array, and return the result.
+ *
+ * @final since 5.4
  */
 class ArrayMergeTask extends AbstractConfigurableTask implements BlockingTaskInterface
 {

src/Task/ColumnAggregatorTask.php

@@ -24,6 +24,8 @@
 /**
  * For each configured column, collect the input rows that contain this column (and match the optional condition), and
  * output all the groups once all previous tasks are resolved.
+ *
+ * @final since 5.4
  */
 class ColumnAggregatorTask extends AbstractConfigurableTask implements BlockingTaskInterface
 {

src/Task/ConstantIterableOutputTask.php

@@ -18,6 +18,8 @@
 
 /**
  * Always send the same output regardless of the input, only accepts array for values and iterate over it.
+ *
+ * @final since 5.4
  */
 class ConstantIterableOutputTask extends AbstractIterableOutputTask
 {

src/Task/ConstantOutputTask.php

@@ -19,6 +19,8 @@
 
 /**
  * Always send the same output regardless of the input.
+ *
+ * @final since 5.4
  */
 class ConstantOutputTask extends AbstractConfigurableTask
 {

src/Task/CounterTask.php

@@ -21,6 +21,8 @@
 /**
  * Count the number of times the task is processed and continue every N iteration (skip the rest of the time)
  * Flush at the end with the actual count.
+ *
+ * @final since 5.4
  */
 class CounterTask extends AbstractConfigurableTask implements FlushableTaskInterface
 {

src/Task/Debug/DebugTask.php

@@ -19,6 +19,8 @@
 
 /**
  * Dump the content of the input.
+ *
+ * @final since 5.4
  */
 class DebugTask implements TaskInterface
 {

src/Task/Debug/DieTask.php

@@ -20,6 +20,8 @@
  * Class DieTask.
  *
  * Stops the process brutally
+ *
+ * @final since 5.4
  */
 class DieTask implements TaskInterface
 {