From 0f46e56f3def4310b5184f8c33fa7bbdf80f1765 Mon Sep 17 00:00:00 2001 From: Nicolas Joubert Date: Wed, 14 Oct 2026 16:48:15 +0200 Subject: [PATCH] #272 - Autoconfigure TaskInterface and TransformerInterface services, add FQCN aliases - registerForAutoconfiguration(TaskInterface): public, not shared, monolog.logger tag on cleverage_process_task. - registerForAutoconfiguration(TransformerInterface): cleverage.transformer tag, monolog.logger tag on cleverage_process_transformer. With autoconfigure: true, applications no longer need _instanceof rules or explicit tags; a setting explicitly defined on a service wins, and identical tags are not duplicated (no double registration in TransformerRegistry). - FQCN aliases (private, for autowiring) for ProcessManager, ProcessConfigurationRegistry, TransformerRegistry and ContextualOptionResolver. - Documentation (quick start, custom tasks, common setup) and tests. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 1 + config/services/manager.yaml | 5 ++ config/services/registry.yaml | 4 ++ docs/01-quick_start.md | 21 ++++--- docs/03-custom_tasks.md | 23 +++++-- docs/cookbooks/01-common_setup.md | 10 ++- .../CleverAgeProcessExtension.php | 10 +++ .../CleverAgeProcessExtensionTest.php | 62 +++++++++++++++++++ 8 files changed, 121 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18f194c5..448edcb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ Latest ------ ## Changes +* [#272](https://github.com/cleverage/process-bundle/issues/272) DependencyInjection: autoconfiguration of the services implementing `TaskInterface` (`public`, not shared, `monolog.logger` tag on `cleverage_process_task`) and `TransformerInterface` (`cleverage.transformer` tag, `monolog.logger` tag on `cleverage_process_transformer`): the `_instanceof` rules or explicit tags are no longer needed with `autoconfigure: true`; a setting explicitly defined on a service wins. Add FQCN aliases to autowire `ProcessManager`, `ProcessConfigurationRegistry`, `TransformerRegistry` and `ContextualOptionResolver`. Update documentation, add tests. * [#274](https://github.com/cleverage/process-bundle/issues/274) CI: test the lowest versions allowed by `composer.json` (`--prefer-lowest`, PHP 8.2). Fix the lower bounds it revealed: require `psr/log` `^2|^3` (`Logger\AbstractLogger` and the loggers of the tests use the typed `LoggerInterface` signatures, a fatal error with `psr/log` 1) and `monolog/monolog` `^3` (the `Logger\*Processor` classes use `Monolog\LogRecord`, Monolog 3 only: a `TypeError` on every log of the `cleverage_process*` channels with Monolog 2). * [#273](https://github.com/cleverage/process-bundle/issues/273) Trigger the deprecations with `trigger_deprecation()` (`symfony/deprecation-contracts`, now required) instead of `@trigger_error(..., E_USER_DEPRECATED)`: the messages are prefixed with the package and the version that introduced the deprecation (e.g. `Since cleverage/process-bundle 5.1: ...`), as for the Symfony packages. Same `E_USER_DEPRECATED` level. Add tests. * [#270](https://github.com/cleverage/process-bundle/issues/270) Add a `.gitattributes`: the development files (`.docker/`, `.github/`, `tests/`, quality tools and PHPUnit configurations, `Makefile`…) are no longer part of the archive installed by Composer (`dist`). Remove the obsolete test fixtures of `src/Resources/tests/` (not used since the tests rewrite). diff --git a/config/services/manager.yaml b/config/services/manager.yaml index 8445bb42..94a7f9c0 100644 --- a/config/services/manager.yaml +++ b/config/services/manager.yaml @@ -11,6 +11,11 @@ services: - '@event_dispatcher' - !tagged_iterator cleverage_process.stop_checker + CleverAge\ProcessBundle\Manager\ProcessManager: + alias: cleverage_process.manager.process + cleverage_process.context.contextual_option_resolver: class: CleverAge\ProcessBundle\Context\ContextualOptionResolver public: false + CleverAge\ProcessBundle\Context\ContextualOptionResolver: + alias: cleverage_process.context.contextual_option_resolver diff --git a/config/services/registry.yaml b/config/services/registry.yaml index f84b16c0..a18f3366 100644 --- a/config/services/registry.yaml +++ b/config/services/registry.yaml @@ -6,7 +6,11 @@ services: - ~ - ~ - ~ + CleverAge\ProcessBundle\Registry\ProcessConfigurationRegistry: + alias: cleverage_process.registry.process_configuration cleverage_process.registry.transformer: class: CleverAge\ProcessBundle\Registry\TransformerRegistry public: false + CleverAge\ProcessBundle\Registry\TransformerRegistry: + alias: cleverage_process.registry.transformer diff --git a/docs/01-quick_start.md b/docs/01-quick_start.md index 739e3e94..00be052b 100644 --- a/docs/01-quick_start.md +++ b/docs/01-quick_start.md @@ -68,8 +68,16 @@ clever_age_process: default_error_strategy: stop ``` -When creating custom tasks and transformers, you can use Symfony automatic registration, but remember there are a few -required configurations: +When creating custom tasks and transformers, you can use Symfony automatic registration. With autoconfiguration +(`autoconfigure: true`, set in the `_defaults` of the Symfony skeleton, so the default `App\:` resource is enough), the +bundle configures them: +- services implementing `CleverAge\ProcessBundle\Model\TaskInterface` are `public` (the process manager fetches tasks + from the container) and not shared (no data shared between task usages), with a `monolog.logger` tag on the + `cleverage_process_task` channel; +- services implementing `CleverAge\ProcessBundle\Transformer\TransformerInterface` get the `cleverage.transformer` tag + (needed by the transformer registry) and a `monolog.logger` tag on the `cleverage_process_transformer` channel. + +Without autoconfiguration, declare these settings yourself: ```yaml # config/services.yaml @@ -77,8 +85,6 @@ services: App\Transformer\: resource: '../src/Transformer/*' autowire: true - autoconfigure: true - public: false tags: - { name: cleverage.transformer } # Needed by the transformer registry to find transformers - { name: monolog.logger, channel: cleverage_process_transformer } # Optional, see logging @@ -86,17 +92,14 @@ services: App\Task\: resource: '../src/Task/*' autowire: true - autoconfigure: true shared: false # Important to avoid shared data between task usages public: true # Needed by the Process Manager to fetch tasks from the container tags: - { name: monolog.logger, channel: cleverage_process_task } # Optional, see logging ``` -The `cleverage.transformer` tag is not added by autoconfiguration: you have to declare it yourself (or use an -`_instanceof` rule on `CleverAge\ProcessBundle\Transformer\TransformerInterface`, which only applies to services -defined in the same file). If your `services.yaml` also has the default `App\:` resource, declare these resources after -it, so that they override its definitions. The `monolog.logger` tags bind injected loggers to the bundle channels (see +If your `services.yaml` also has the default `App\:` resource, declare these resources after it, so that they override +its definitions. The `monolog.logger` tags bind injected loggers to the bundle channels (see [logging](03-custom_tasks.md#logging)). ## Process definition diff --git a/docs/03-custom_tasks.md b/docs/03-custom_tasks.md index f0cacf9d..5bab561a 100644 --- a/docs/03-custom_tasks.md +++ b/docs/03-custom_tasks.md @@ -18,6 +18,11 @@ same service, or even with another instance of your process. Since a task is a s create one instance (keeping values in every attribute of your class). With `shared: false`, a new instance is created each time a task configuration is initialized. +With autoconfiguration (`autoconfigure: true`, set in the `_defaults` of the Symfony skeleton), the bundle applies +these settings to every service implementing `TaskInterface`: `public: true`, `shared: false` and a `monolog.logger` +tag on the `cleverage_process_task` channel (see [logging](#logging)). A setting explicitly defined on the service +wins (e.g. `shared: true`). + ```yaml # config/services.yaml services: @@ -25,6 +30,16 @@ services: resource: '../src/Task/*' autowire: true autoconfigure: true +``` + +Without autoconfiguration, declare them explicitly: + +```yaml +# config/services.yaml +services: + App\Task\: + resource: '../src/Task/*' + autowire: true public: true shared: false tags: @@ -182,7 +197,8 @@ must skip the state (`ProcessState::setSkipped(true)`) instead of outputting the Transformers are another kind of service. They implement `CleverAge\ProcessBundle\Transformer\TransformerInterface` (`transform(mixed $value, array $options = []): mixed` and `getCode(): string`) or `CleverAge\ProcessBundle\Transformer\ConfigurableTransformerInterface` (which adds -`configureOptions(OptionsResolver $resolver): void`) and are declared with a `cleverage.transformer` tag. +`configureOptions(OptionsResolver $resolver): void`) and are declared with a `cleverage.transformer` tag (added by +autoconfiguration, with a `monolog.logger` tag on the `cleverage_process_transformer` channel). They're meant to be lightweight, composable, and stateless pieces of your process. Feel free to implement custom ones as soon as provided ones don't fit your goal. @@ -219,8 +235,7 @@ services: App\Transformer\: resource: '../src/Transformer/*' autowire: true - tags: - - { name: cleverage.transformer } + autoconfigure: true # or, without autoconfiguration: tags: [{ name: cleverage.transformer }] ``` Once properly set up, they are registered in the `CleverAge\ProcessBundle\Registry\TransformerRegistry` (used by the @@ -252,7 +267,7 @@ Each channel has a Monolog processor that adds the following values in the `extr if any) for the task and transformer channels. To benefit from those in your own tasks, inject a `Psr\Log\LoggerInterface` and bind it to the task channel with the -`monolog.logger` tag: +`monolog.logger` tag (added by autoconfiguration, see [service declaration](#service-declaration)): ```yaml services: diff --git a/docs/cookbooks/01-common_setup.md b/docs/cookbooks/01-common_setup.md index f35ab40f..1ecedf4e 100644 --- a/docs/cookbooks/01-common_setup.md +++ b/docs/cookbooks/01-common_setup.md @@ -4,7 +4,12 @@ Common Setup Task & transformer declaration ------------------------------ -Example of a generic declaration for all the tasks and transformers of your application: +With autoconfiguration (`autoconfigure: true`, set in the `_defaults` of the Symfony skeleton), nothing more is needed: +the bundle makes the services implementing `CleverAge\ProcessBundle\Model\TaskInterface` public and not shared, tags +the ones implementing `CleverAge\ProcessBundle\Transformer\TransformerInterface` with `cleverage.transformer`, and binds +both to their logging channel (`monolog.logger` tags). + +Without autoconfiguration, example of a generic declaration for all the tasks and transformers of your application: ```yaml # config/services.yaml @@ -29,7 +34,8 @@ services: If the file also contains the default `App\:` resource (which includes `src/Task/` and `src/Transformer/`), declare these resources after it: the last definition of a service wins. -Alternatively, you can use `_instanceof` rules to configure every class implementing +Alternatively (still without autoconfiguration, or to override these settings), you can use `_instanceof` rules to +configure every class implementing `CleverAge\ProcessBundle\Model\TaskInterface` or `CleverAge\ProcessBundle\Transformer\TransformerInterface`, wherever it is located in your sources (`_instanceof` only applies to the services defined in the same file, typically by the `App\:` resource of `config/services.yaml`): diff --git a/src/DependencyInjection/CleverAgeProcessExtension.php b/src/DependencyInjection/CleverAgeProcessExtension.php index 9ed62114..9777e2c0 100644 --- a/src/DependencyInjection/CleverAgeProcessExtension.php +++ b/src/DependencyInjection/CleverAgeProcessExtension.php @@ -14,7 +14,9 @@ namespace CleverAge\ProcessBundle\DependencyInjection; use CleverAge\ProcessBundle\Model\ProcessStopCheckerInterface; +use CleverAge\ProcessBundle\Model\TaskInterface; use CleverAge\ProcessBundle\Transformer\GenericTransformer; +use CleverAge\ProcessBundle\Transformer\TransformerInterface; use Symfony\Component\Config\FileLocator; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Definition; @@ -36,6 +38,14 @@ public function load(array $configs, ContainerBuilder $container): void $container->registerForAutoconfiguration(ProcessStopCheckerInterface::class) ->addTag('cleverage_process.stop_checker'); + // Tasks are fetched from the container by the process manager, and keep state between executions + $container->registerForAutoconfiguration(TaskInterface::class) + ->setPublic(true) + ->setShared(false) + ->addTag('monolog.logger', ['channel' => 'cleverage_process_task']); + $container->registerForAutoconfiguration(TransformerInterface::class) + ->addTag('cleverage.transformer') + ->addTag('monolog.logger', ['channel' => 'cleverage_process_transformer']); $configuration = new Configuration(); $config = $this->processConfiguration($configuration, $configs); diff --git a/tests/DependencyInjection/CleverAgeProcessExtensionTest.php b/tests/DependencyInjection/CleverAgeProcessExtensionTest.php index 6002cf63..74c5f496 100644 --- a/tests/DependencyInjection/CleverAgeProcessExtensionTest.php +++ b/tests/DependencyInjection/CleverAgeProcessExtensionTest.php @@ -13,14 +13,25 @@ namespace CleverAge\ProcessBundle\Tests\DependencyInjection; +use CleverAge\ProcessBundle\Context\ContextualOptionResolver; use CleverAge\ProcessBundle\DependencyInjection\CleverAgeProcessExtension; use CleverAge\ProcessBundle\DependencyInjection\Configuration; +use CleverAge\ProcessBundle\Manager\ProcessManager; use CleverAge\ProcessBundle\Model\ProcessStopCheckerInterface; +use CleverAge\ProcessBundle\Registry\ProcessConfigurationRegistry; +use CleverAge\ProcessBundle\Registry\TransformerRegistry; +use CleverAge\ProcessBundle\Task\DummyTask; +use CleverAge\ProcessBundle\Transformer\String\TrimTransformer; +use CleverAge\ProcessBundle\Transformer\TransformerInterface; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\UsesClass; use PHPUnit\Framework\TestCase; use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; +use Symfony\Component\DependencyInjection\ChildDefinition; +use Symfony\Component\DependencyInjection\Compiler\ResolveChildDefinitionsPass; +use Symfony\Component\DependencyInjection\Compiler\ResolveInstanceofConditionalsPass; use Symfony\Component\DependencyInjection\ContainerBuilder; +use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\Yaml\Yaml; #[CoversClass(CleverAgeProcessExtension::class)] @@ -57,6 +68,57 @@ public function testEveryServiceDefinitionFileIsLoaded(): void } } + public function testServicesCanBeAutowiredByClassName(): void + { + $container = new ContainerBuilder(); + (new CleverAgeProcessExtension())->load([], $container); + + foreach ([ + ProcessManager::class => 'cleverage_process.manager.process', + ProcessConfigurationRegistry::class => 'cleverage_process.registry.process_configuration', + TransformerRegistry::class => 'cleverage_process.registry.transformer', + ContextualOptionResolver::class => 'cleverage_process.context.contextual_option_resolver', + ] as $class => $id) { + self::assertSame($id, (string) $container->getAlias($class)); + self::assertSame($class, $container->getDefinition($id)->getClass()); + } + } + + public function testTasksAndTransformersAreAutoconfigured(): void + { + $container = new ContainerBuilder(); + (new CleverAgeProcessExtension())->load([], $container); + + // Application services, autoconfigured + $container->setDefinition('app.task', (new Definition(DummyTask::class))->setAutoconfigured(true)); + $container->setDefinition('app.shared_task', (new Definition(DummyTask::class))->setAutoconfigured(true)->setShared(true)); + $container->setDefinition('app.transformer', (new Definition(TrimTransformer::class))->setAutoconfigured(true)); + // An application keeping its own "_instanceof" rule, as documented before + $container->setDefinition('app.instanceof_transformer', (new Definition(TrimTransformer::class)) + ->setAutoconfigured(true) + ->setInstanceofConditionals([ + TransformerInterface::class => (new ChildDefinition(''))->addTag('cleverage.transformer'), + ])); + (new ResolveInstanceofConditionalsPass())->process($container); + (new ResolveChildDefinitionsPass())->process($container); + + $task = $container->getDefinition('app.task'); + self::assertTrue($task->isPublic()); + self::assertFalse($task->isShared()); + self::assertSame([['channel' => 'cleverage_process_task']], $task->getTag('monolog.logger')); + // An explicit configuration of the service wins + self::assertTrue($container->getDefinition('app.shared_task')->isShared()); + + foreach (['app.transformer', 'app.instanceof_transformer'] as $id) { + $transformer = $container->getDefinition($id); + // Registered once in the transformer registry (no duplicate tag) + self::assertSame([[]], $transformer->getTag('cleverage.transformer'), $id); + self::assertSame([['channel' => 'cleverage_process_transformer']], $transformer->getTag('monolog.logger'), $id); + } + // The bundle transformers (autoconfigured, tagged explicitly) are not tagged twice + self::assertSame([[]], $container->getDefinition(TrimTransformer::class)->getTag('cleverage.transformer')); + } + public function testStopCheckersAreInjectedInTheProcessManager(): void { $container = new ContainerBuilder();