Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
5 changes: 5 additions & 0 deletions config/services/manager.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 4 additions & 0 deletions config/services/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
21 changes: 12 additions & 9 deletions docs/01-quick_start.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,35 +68,38 @@ 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
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

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
Expand Down
23 changes: 19 additions & 4 deletions docs/03-custom_tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,28 @@ 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:
App\Task\:
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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
10 changes: 8 additions & 2 deletions docs/cookbooks/01-common_setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`):
Expand Down
10 changes: 10 additions & 0 deletions src/DependencyInjection/CleverAgeProcessExtension.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);
Expand Down
62 changes: 62 additions & 0 deletions tests/DependencyInjection/CleverAgeProcessExtensionTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down Expand Up @@ -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();
Expand Down
Loading