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
* [#275](https://github.com/cleverage/process-bundle/issues/275) The tasks are fetched from a service locator built at compile time from the services referenced by the process configurations (new `TaskRegistry`, `cleverage_process.registry.task`, and internal `TaskLocatorCompilerPass`) instead of the whole service container: a task service can be private. `ProcessManager` and `ProcessHelpCommand` get the registry as a new optional last constructor argument; not passing it is deprecated (the tasks are then fetched from the container), and fetching a task service not referenced by the process configurations known at compile time falls back on the container with a deprecation. Both fallbacks will be removed in v6.0 (#114). Update documentation, add tests.
* [#278](https://github.com/cleverage/process-bundle/issues/278) The container no longer fails to compile when the Symfony serializer or validator is not enabled: the tasks and transformers depending on them (`NormalizerTask`, `DenormalizerTask`, `SerializerTask`, `DeserializerTask`, `normalize` and `denormalize` transformers, `ValidatorTask`) are replaced by services failing with an explicit message when they are used (new internal `UnavailableServicesCompilerPass`). `CheckSerializerCompilerPass` is no longer used and deprecated. Update documentation, add tests.
* [#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).
Expand Down
1 change: 1 addition & 0 deletions config/services/command.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ services:
arguments:
- '@cleverage_process.registry.process_configuration'
- '@service_container'
- '@cleverage_process.registry.task'
1 change: 1 addition & 0 deletions config/services/manager.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ services:
- '@cleverage_process.context.contextual_option_resolver'
- '@event_dispatcher'
- !tagged_iterator cleverage_process.stop_checker
- '@cleverage_process.registry.task'

CleverAge\ProcessBundle\Manager\ProcessManager:
alias: cleverage_process.manager.process
Expand Down
9 changes: 9 additions & 0 deletions config/services/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,12 @@ services:
public: false
CleverAge\ProcessBundle\Registry\TransformerRegistry:
alias: cleverage_process.registry.transformer

cleverage_process.registry.task:
class: CleverAge\ProcessBundle\Registry\TaskRegistry
public: false
arguments:
- ~ # Service locator of the task services, see TaskLocatorCompilerPass
- '@service_container' # Deprecated fallback, removed in v6.0
CleverAge\ProcessBundle\Registry\TaskRegistry:
alias: cleverage_process.registry.task
6 changes: 2 additions & 4 deletions docs/01-quick_start.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,8 @@ clever_age_process:
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\Model\TaskInterface` are 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.

Expand All @@ -99,7 +98,6 @@ services:
resource: '../src/Task/*'
autowire: 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
```
Expand Down
16 changes: 9 additions & 7 deletions docs/03-custom_tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,12 @@ create your own.

As stated before, tasks are simple services implementing `CleverAge\ProcessBundle\Model\TaskInterface`, so you can
design them like any other service, with only small specificities:
- the service must be **public**: the process manager fetches it from the container using the `service` reference of
the task configuration (with or without the leading `@`)
- the service does **not need to be public**: the process manager fetches it, using the `service` reference of the
task configuration (a service id or alias, with or without the leading `@`, see
[task definition](reference/02-task_definition.md#task-attributes)), from a service locator built from the process
configurations when the container is compiled. Only a service that is not referenced by these configurations (e.g. a
configuration added at runtime) is fetched from the service container, which requires a public service and is
deprecated
- the service should **not be shared** ([`shared: false`](https://symfony.com/doc/current/service_container/shared.html))

Most of the time you don't want a task declared in a process to share some data with another declaration using the
Expand All @@ -19,9 +23,9 @@ create one instance (keeping values in every attribute of your class). With `sha
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`).
these settings to every service implementing `TaskInterface`: `shared: false` and a `monolog.logger` tag on the
`cleverage_process_task` channel (see [logging](#logging)), as well as `public: true`, only kept for the deprecated
fallback on the service container. A setting explicitly defined on the service wins (e.g. `shared: true`).

```yaml
# config/services.yaml
Expand All @@ -40,7 +44,6 @@ services:
App\Task\:
resource: '../src/Task/*'
autowire: true
public: true
shared: false
tags:
- { name: monolog.logger, channel: cleverage_process_task }
Expand Down Expand Up @@ -274,7 +277,6 @@ services:
App\Task\:
resource: '../src/Task/*'
autowire: true
public: true
shared: false
tags:
- { name: monolog.logger, channel: cleverage_process_task }
Expand Down
2 changes: 1 addition & 1 deletion docs/05-good_practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ in several places, declare it once as a [generic transformer](reference/03-gener

## Declare tasks as non-shared services

Task services must be `public: true` and should be `shared: false`: a task often keeps state in its properties (an
Task services should be `shared: false`: a task often keeps state in its properties (an
open file, a buffer, a counter...). A shared service would share this state between two tasks using the same service
in a process, or between two executions of a process in the same PHP process (sub-processes, workers, tests). See
[service declaration](03-custom_tasks.md#service-declaration).
Expand Down
5 changes: 1 addition & 4 deletions docs/cookbooks/01-common_setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Task & transformer declaration
------------------------------

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 bundle makes the services implementing `CleverAge\ProcessBundle\Model\TaskInterface` not shared, tags
the ones implementing `CleverAge\ProcessBundle\Transformer\TransformerInterface` with `cleverage.transformer`, and binds
both to their logging channel (`monolog.logger` tags).

Expand All @@ -17,15 +17,13 @@ services:
App\Task\:
resource: '../src/Task/*'
autowire: true
public: true
shared: false
tags:
- { name: monolog.logger, channel: cleverage_process_task }

App\Transformer\:
resource: '../src/Transformer/*'
autowire: true
public: false
tags:
- { name: cleverage.transformer }
- { name: monolog.logger, channel: cleverage_process_transformer }
Expand All @@ -44,7 +42,6 @@ it is located in your sources (`_instanceof` only applies to the services define
services:
_instanceof:
CleverAge\ProcessBundle\Model\TaskInterface:
public: true
shared: false
tags:
- { name: monolog.logger, channel: cleverage_process_task }
Expand Down
23 changes: 21 additions & 2 deletions docs/reference/02-task_definition.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,27 @@ YAML Configuration
Task attributes
---------------

**service**: required, reference to the service used for the task, with or without a leading `@`. The service must be
public and implement `CleverAge\ProcessBundle\Model\TaskInterface`.
**service**: required, reference to the service used for the task: a service **id** or a service **alias**, with or
without a leading `@` (quote the value when it starts with `@`, as YAML requires). The service must implement
`CleverAge\ProcessBundle\Model\TaskInterface`. For instance, the `UnzipTask` of the archive bridge is registered as
`cleverage_archive_process.task.unzip`, with an alias named after its class: these four references are equivalent.

```yaml
service: '@cleverage_archive_process.task.unzip' # id, with @
service: cleverage_archive_process.task.unzip # id, without @
service: '@CleverAge\ArchiveProcessBundle\Task\UnzipTask' # alias, with @
service: CleverAge\ArchiveProcessBundle\Task\UnzipTask # alias, without @
```

The tasks of this bundle are registered with their class name as id (e.g. `'@CleverAge\ProcessBundle\Task\TransformerTask'`),
the tasks of the bridge bundles with a `cleverage_*_process.task.*` id and an alias named after their class, and your
own task services with any id or alias you choose. With an unknown service, a reference with `@` throws the
`ServiceNotFoundException` of the service container, a reference without `@` an `\UnexpectedValueException`
(`Unable to resolve service reference for Task '<task code>'`).

The services referenced by the process configurations are collected when the container is compiled, so they can be
private (as well as the aliases). Only a service that is not referenced by these configurations (e.g. a configuration
added at runtime) is fetched from the service container, which requires a public service and is deprecated since 5.4.

**description**: optional string to describe a task, displayed in process help (should not exceed one line).

Expand Down
2 changes: 2 additions & 0 deletions src/CleverAgeProcessBundle.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
namespace CleverAge\ProcessBundle;

use CleverAge\ProcessBundle\DependencyInjection\Compiler\RegistryCompilerPass;
use CleverAge\ProcessBundle\DependencyInjection\Compiler\TaskLocatorCompilerPass;
use CleverAge\ProcessBundle\DependencyInjection\Compiler\UnavailableServicesCompilerPass;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Bundle\Bundle;
Expand All @@ -32,6 +33,7 @@ public function build(ContainerBuilder $container): void
);

$container->addCompilerPass(new UnavailableServicesCompilerPass());
$container->addCompilerPass(new TaskLocatorCompilerPass());
}

#[\Override]
Expand Down
33 changes: 17 additions & 16 deletions src/Command/ProcessHelpCommand.php
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
use CleverAge\ProcessBundle\Model\IterableTaskInterface;
use CleverAge\ProcessBundle\Model\TaskInterface;
use CleverAge\ProcessBundle\Registry\ProcessConfigurationRegistry;
use CleverAge\ProcessBundle\Registry\TaskRegistry;
use CleverAge\ProcessBundle\Task\Process\ProcessExecutorTask;
use CleverAge\ProcessBundle\Task\Process\ProcessLauncherTask;
use Psr\Container\ContainerInterface;
Expand Down Expand Up @@ -59,11 +60,26 @@ class ProcessHelpCommand extends Command

protected const INDENT_SIZE = 4;

protected TaskRegistry $taskRegistry;

public function __construct(
protected ProcessConfigurationRegistry $processConfigRegistry,
protected ContainerInterface $container,
?TaskRegistry $taskRegistry = null,
) {
parent::__construct();
if (!$taskRegistry instanceof TaskRegistry) {
trigger_deprecation(
'cleverage/process-bundle',
'5.4',
'Not passing a "%s" to "%s::__construct()" is deprecated: the tasks are fetched from the service container. The argument will be required in v6.0.',
TaskRegistry::class,
self::class,
);
// Same behaviour as before the task registry: any service of the container
$taskRegistry = new TaskRegistry($this->container, $this->container);
}
$this->taskRegistry = $taskRegistry;
}

protected function configure(): void
Expand Down Expand Up @@ -534,21 +550,6 @@ protected function getTaskDescription(TaskConfiguration $task): string

protected function getTaskService(TaskConfiguration $taskConfiguration): TaskInterface
{
// Duplicate code from \CleverAge\ProcessBundle\Manager\ProcessManager::initialize
// @todo Refactor this using a Registry with this feature:
// https://symfony.com/doc/current/service_container/service_subscribers_locators.html
$serviceReference = $taskConfiguration->getServiceReference();
if (str_starts_with($serviceReference, '@')) {
$task = $this->container->get(ltrim($serviceReference, '@'));
} elseif ($this->container->has($serviceReference)) {
$task = $this->container->get($serviceReference);
} else {
throw new \UnexpectedValueException("Unable to resolve service reference for Task '{$taskConfiguration->getCode()}'");
}
if (!$task instanceof TaskInterface) {
throw new \UnexpectedValueException("Service defined in Task '{$taskConfiguration->getCode()}' is not a TaskInterface");
}

return $task;
return $this->taskRegistry->getTask($taskConfiguration);
}
}
53 changes: 53 additions & 0 deletions src/DependencyInjection/Compiler/TaskLocatorCompilerPass.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php

declare(strict_types=1);

/*
* This file is part of the CleverAge/ProcessBundle package.
*
* Copyright (c) Clever-Age
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

namespace CleverAge\ProcessBundle\DependencyInjection\Compiler;

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\Compiler\ServiceLocatorTagPass;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;

/**
* Builds the service locator of the task registry from the services referenced by the process configurations, so
* that the tasks are not fetched from the whole service container.
*
* @internal
*/
final class TaskLocatorCompilerPass implements CompilerPassInterface
{
public function process(ContainerBuilder $container): void
{
if (!$container->hasDefinition('cleverage_process.registry.task')
|| !$container->hasDefinition('cleverage_process.registry.process_configuration')) {
return;
}

$configurations = $container->getParameterBag()->resolveValue(
$container->getDefinition('cleverage_process.registry.process_configuration')->getArgument(0)
);
$services = [];
foreach (\is_array($configurations) ? $configurations : [] as $configuration) {
foreach ($configuration['tasks'] ?? [] as $task) {
$id = ltrim((string) ($task['service'] ?? ''), '@');
// Unknown services keep failing at runtime, with the same message
if ('' !== $id && $container->has($id)) {
$services[$id] = new Reference($id);
}
}
}

$container->getDefinition('cleverage_process.registry.task')
->replaceArgument(0, ServiceLocatorTagPass::register($container, $services));
}
}
30 changes: 17 additions & 13 deletions src/Manager/ProcessManager.php
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
use CleverAge\ProcessBundle\Model\ProcessStopCheckerInterface;
use CleverAge\ProcessBundle\Model\TaskInterface;
use CleverAge\ProcessBundle\Registry\ProcessConfigurationRegistry;
use CleverAge\ProcessBundle\Registry\TaskRegistry;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;

Expand Down Expand Up @@ -60,6 +61,8 @@ class ProcessManager

protected ?TaskConfiguration $taskConfiguration = null;

protected TaskRegistry $taskRegistry;

/**
* @param iterable<ProcessStopCheckerInterface> $stopCheckers
*/
Expand All @@ -71,7 +74,20 @@ public function __construct(
protected ContextualOptionResolver $contextualOptionResolver,
protected EventDispatcherInterface $eventDispatcher,
protected iterable $stopCheckers = [],
?TaskRegistry $taskRegistry = null,
) {
if (!$taskRegistry instanceof TaskRegistry) {
trigger_deprecation(
'cleverage/process-bundle',
'5.4',
'Not passing a "%s" to "%s::__construct()" is deprecated: the tasks are fetched from the service container. The argument will be required in v6.0.',
TaskRegistry::class,
self::class,
);
// Same behaviour as before the task registry: any service of the container
$taskRegistry = new TaskRegistry($this->container, $this->container);
}
$this->taskRegistry = $taskRegistry;
}

public function getProcessHistory(): ?ProcessHistory
Expand Down Expand Up @@ -250,19 +266,7 @@ protected function initialize(TaskConfiguration $taskConfiguration): void
$m .= "but it's error strategy 'stop' implies they will never be reached.";
$this->taskLogger->debug($m);
}
// @todo Refactor this using a Registry with this feature:
// https://symfony.com/doc/current/service_container/service_subscribers_locators.html
$serviceReference = $taskConfiguration->getServiceReference();
if (str_starts_with($serviceReference, '@')) {
$task = $this->container->get(ltrim($serviceReference, '@'));
} elseif ($this->container->has($serviceReference)) {
$task = $this->container->get($serviceReference);
} else {
throw new \UnexpectedValueException("Unable to resolve service reference for Task '{$taskConfiguration->getCode()}'");
}
if (!$task instanceof TaskInterface) {
throw new \UnexpectedValueException("Service defined in Task '{$taskConfiguration->getCode()}' is not a TaskInterface");
}
$task = $this->taskRegistry->getTask($taskConfiguration);
$taskConfiguration->setTask($task);

if ($task instanceof InitializableTaskInterface) {
Expand Down
Loading
Loading