#475 - Generic transformers: restore, deprecated, the former names of the dashed transformer codes and contextual options

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: njoubert-cleverage

CHANGELOG.md

@@ -6,6 +6,7 @@ Latest
 * [#483](https://github.com/cleverage/process-bundle/issues/483) Documentation: an exception thrown by `IterableTaskInterface::next()` makes the process fail right away with this exception, the `error_strategy` and the `error_outputs` of the task do not apply.
 
 ## Fixes
+* [#475](https://github.com/cleverage/process-bundle/issues/475) Generic transformers: restore, deprecated, the former names (with underscores instead of dashes) of their transformer codes and contextual options, which no longer worked since 5.9 ([#438](https://github.com/cleverage/process-bundle/issues/438)): a transformer code with a dash that is only registered with underscores (`array-first` for `array_first`), and a contextual option with a dash given or used by its former name (`the_prefix`, `{{ the_prefix }}` for `the-prefix`). Update documentation, add tests.
 * [#477](https://github.com/cleverage/process-bundle/issues/477) "Stop the process on the first invalid item" (`error_strategy: skip` and an error branch ending on a `StopTask`) ends as stopped when the failing task is finalizable (`csv_reader`, `xml_stream_reader`, `stat_counter`...): the error of the skipped item, kept by its state, was taken for a finalization failure and the process ended as failed. Add tests.
 * [#473](https://github.com/cleverage/process-bundle/issues/473) A task failing with the `stop` error strategy makes the process fail even when its error branch stops the flow (`StopTask`, `ProcessState::stop()`): the failure was swallowed, the process ended as succeeded or stopped (`cleverage_process.end` event, exit code 0) and a parent process went on with a `null` output. Update documentation, add tests.
 * [#485](https://github.com/cleverage/process-bundle/issues/485) The process returns the last output of its `end_point` passed on to the next tasks: the output of an execution whose output is ignored (skipped, filtered, failed with the `skip` strategy) was returned, e.g. `""` for a `skip_empty` end point whose last item is empty, or `null` for a filtered last item. Update documentation, add tests.
@@ -397,7 +398,6 @@ v3.2.2
 * `\CleverAge\ProcessBundle\Exception\InvalidProcessConfigurationException` now displays the failing process code
 * `\CleverAge\ProcessBundle\Transformer\TransformerTrait` now displays a more explicit message on wrong options type
 
-
 v3.2.1
 ------
 
@@ -418,8 +418,6 @@ v3.2.0
 There is no BC break for this version, but note that `sidus/base-bundle` has been removed from dependencies.
 If you use it, it should already be inside your own composer.json.
 
-
-
 Release v3.1
 ============
 
@@ -445,15 +443,13 @@ v3.1.5
 
 * [GITHUB-120](https://github.com/cleverage/process-bundle/pull/120): FolderBrowserTask: Accept array type for `name_pattern` option
 
-
 v3.1.4
 ------
 
 ### Features
 
 * (_backport from v3.0.9_) Adding simple task to launch system commands
 
-
 v3.1.3
 ------
 
@@ -509,7 +505,6 @@ v3.1.0
 * [GITHUB-106](https://github.com/cleverage/process-bundle/issues/106): an entry-point cannot have an ancestor anymore.
   The behaviour was undefined, and now it will throw an exception.
 
-
 UPGRADE TO 2.0
 ==============
 
@@ -533,7 +528,6 @@ options:
                 <key>: <options>
 ```
 
-
 UPGRADE TO 1.1
 ==============
 

UPGRADE.md

@@ -11,6 +11,16 @@ as succeeded or stopped. To stop the process on purpose on the first error (not
 on the failing task, as in the "Stop the process on the first invalid item" example of the
 [StopTask](docs/reference/tasks/stop_task.md).
 
+### Dashes in the generic transformers
+
+Since 5.9, the codes of the transformers and of the contextual options of a generic transformer keep their dashes, as
+written. Before 5.9, they were replaced by underscores (unless the code also had an underscore), and only their former
+name worked: `array-first` was found as the `array_first` transformer, and a `the-prefix` contextual option was given
+and used as `the_prefix` / `{{ the_prefix }}`. These former names work again but are deprecated since 5.10 (`Since
+cleverage/process-bundle 5.10: The transformer "array-first" of the generic transformer...`, `Using the contextual option
+"the-prefix" of the generic transformer...`), and will not work in 6.0: write the code of the transformer as registered
+(`array_first`), and the contextual option as defined in `contextual_options` (`the-prefix`, `{{ the-prefix }}`).
+
 ## v5.8
 
 ### Unknown task references

docs/reference/03-generic_transformers_definition.md

@@ -86,4 +86,7 @@ clever_age_process:
 
 As any transformer code, generic transformer codes must be unique: use a prefix to avoid conflicts. A dash is kept in
 the code (it was replaced by an underscore before 5.7, the former name is deprecated), as in the codes of the
-transformers and of the contextual options of a generic transformer.
+transformers and of the contextual options of a generic transformer (replaced by an underscore before 5.9, unless the
+code also had an underscore: `array-first` was found as the `array_first` transformer, and the `the-prefix` contextual
+option was given and used as `the_prefix` / `{{ the_prefix }}`; these former names still work but are deprecated since
+5.10, write the code of the transformer and of the contextual option as registered).

src/DependencyInjection/Configuration.php

@@ -106,14 +106,16 @@ protected function appendTransformerConfigDefinition(NodeBuilder $definition): v
             ->info('Options of the transformer (code: definition with required, default, default_is_null), injected in the "transformers" with "{{ code }}"')
             ->example(['delimiter' => ['default' => ',']])
             // Keep the dashes of the option codes, as written in the options given to the transformer and in "{{ code }}"
+            // (their former name, with underscores, is deprecated, see GenericTransformer)
             ->normalizeKeys(false)
             ->variablePrototype()
             ->end()
             ->end()
             ->arrayNode('transformers')
             ->info('Transformers applied in sequence, by code, with their options')
             ->example(['explode' => ['delimiter' => '{{ separator }}']])
-            // Keep the dashes of the transformer codes (the former name of a generic transformer is deprecated)
+            // Keep the dashes of the transformer codes (the former name of a generic transformer is deprecated, as the
+            // former name of a transformer code that is only registered with underscores, see GenericTransformer)
             ->normalizeKeys(false)
             ->variablePrototype()
             ->end()

src/Transformer/GenericTransformer.php

@@ -13,10 +13,12 @@
 
 namespace CleverAge\ProcessBundle\Transformer;
 
+use CleverAge\ProcessBundle\Configuration\DeprecatedCodeAliases;
 use CleverAge\ProcessBundle\Context\ContextualOptionResolver;
 use CleverAge\ProcessBundle\Exception\InvalidArgumentException;
 use CleverAge\ProcessBundle\Exception\LogicException;
 use CleverAge\ProcessBundle\Registry\TransformerRegistry;
+use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
 use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
@@ -41,6 +43,15 @@ class GenericTransformer implements ConfigurableTransformerInterface
      */
     protected ?array $contextualOptions = null;
 
+    /**
+     * Former name (with underscores instead of dashes, before 5.9) of the contextual options whose code has a dash.
+     *
+     * Deprecated since 5.10, the former names will not be accepted in v6.0.
+     *
+     * @var array<string, string> former name => code
+     */
+    private array $deprecatedContextualOptions = [];
+
     public function __construct(
         protected ContextualOptionResolver $contextualOptionResolver,
         TransformerRegistry $transformerRegistry,
@@ -61,7 +72,13 @@ public function initialize(string $code, array $options = []): void
 
         $initialOptions = $resolver->resolve($options);
         $this->contextualOptions = $initialOptions['contextual_options'];
-        $this->preconfiguredTransformerOptions = $initialOptions['transformers'];
+        $this->deprecatedContextualOptions = DeprecatedCodeAliases::create(array_keys($this->contextualOptions));
+        $transformers = $initialOptions['transformers'];
+        if (\is_array($transformers)) {
+            $transformers = $this->replaceFormerTransformerCodes($transformers);
+            $this->checkFormerContextualOptionPlaceholders($transformers);
+        }
+        $this->preconfiguredTransformerOptions = $transformers;
     }
 
     /**
@@ -91,6 +108,11 @@ public function configureInitialOptions(OptionsResolver $resolver): void
     public function configureOptions(OptionsResolver $resolver): void
     {
         foreach ($this->contextualOptions ?? [] as $option => $optionConfig) {
+            $formerName = array_search($option, $this->deprecatedContextualOptions, true);
+            if (false !== $formerName) {
+                $this->configureFormerContextualOption($resolver, $option, $formerName, $optionConfig);
+                continue;
+            }
             $resolver->setDefined($option);
             if (null !== $optionConfig['default'] || $optionConfig['default_is_null']) {
                 $resolver->setDefault($option, $optionConfig['default']);
@@ -148,6 +170,10 @@ public function normalizeTransformerOptions(Options $options, array $transformer
                 ? $options[$contextualOption]
                 : null;
         }
+        // The former name of a contextual option whose code has a dash, in "{{ former_name }}" (deprecated)
+        foreach ($this->deprecatedContextualOptions as $formerName => $contextualOption) {
+            $contextualizedOptionValues[$formerName] = $contextualizedOptionValues[$contextualOption] ?? null;
+        }
 
         return $this->contextualOptionResolver->contextualizeOptions($transformerOptions, $contextualizedOptionValues);
     }
@@ -165,4 +191,154 @@ public function configureContextualOptions(OptionsResolver $resolver): void
         $resolver->setDefault('default_is_null', false);
         $resolver->setAllowedTypes('default_is_null', 'bool');
     }
+
+    /**
+     * Before 5.9, the dashes of the transformer codes of a generic transformer were replaced by underscores (unless the
+     * code also had an underscore): "array-first" was found as "array_first". Such a code, when it is not registered
+     * but its former name is, is replaced by its former name (deprecated).
+     *
+     * Deprecated since 5.10, will be removed in v6.0.
+     *
+     * @param array<int|string, mixed> $transformers
+     *
+     * @return array<int|string, mixed>
+     */
+    private function replaceFormerTransformerCodes(array $transformers): array
+    {
+        if (array_is_list($transformers)) {
+            return $transformers;
+        }
+        $replaced = [];
+        foreach ($transformers as $key => $transformerOptions) {
+            $key = $this->replaceFormerTransformerCode($key, $transformers);
+            $replaced[$key] = $transformerOptions;
+        }
+
+        return $replaced;
+    }
+
+    /**
+     * @param array<int|string, mixed> $transformers
+     */
+    private function replaceFormerTransformerCode(int|string $key, array $transformers): int|string
+    {
+        if (!\is_string($key) || !str_contains($key, '-') || str_contains($key, '_')) {
+            return $key;
+        }
+        $formerKey = str_replace('-', '_', $key);
+        // Both were written: none was renamed
+        if (\array_key_exists($formerKey, $transformers)) {
+            return $key;
+        }
+        // The code, without the "#" suffix of the key
+        $code = explode('#', $key, 2)[0];
+        $formerCode = str_replace('-', '_', $code);
+        $registry = $this->transformerRegistry;
+        if (!$registry instanceof TransformerRegistry || $registry->hasTransformer($code) || !$registry->hasTransformer($formerCode)) {
+            return $key;
+        }
+        trigger_deprecation(
+            'cleverage/process-bundle',
+            '5.10',
+            'The transformer "%s" of the generic transformer "%s" is not registered, its former name "%s", with underscores instead of dashes, is used: write "%s". The dashes of the transformer codes of a generic transformer were replaced by underscores before 5.9, the former name will not be used in v6.0.',
+            $code,
+            $this->transformerCode,
+            $formerCode,
+            $formerCode,
+        );
+
+        return $formerKey;
+    }
+
+    /**
+     * Before 5.9, a contextual option whose code has a dash was named with underscores, also in "{{ former_name }}".
+     *
+     * Deprecated since 5.10, will be removed in v6.0.
+     *
+     * @param array<int|string, mixed> $transformers
+     */
+    private function checkFormerContextualOptionPlaceholders(array $transformers): void
+    {
+        if ([] === $this->deprecatedContextualOptions) {
+            return;
+        }
+        $formerNames = array_map(static fn (string $formerName): string => preg_quote($formerName, '/'), array_keys($this->deprecatedContextualOptions));
+        $pattern = \sprintf('/{{[ ]*(%s)[ ]*}}/', implode('|', $formerNames));
+        $used = [];
+        foreach (self::getStrings($transformers) as $string) {
+            if (preg_match_all($pattern, $string, $matches)) {
+                $used = [...$used, ...$matches[1]];
+            }
+        }
+        foreach (array_unique($used) as $formerName) {
+            trigger_deprecation(
+                'cleverage/process-bundle',
+                '5.10',
+                'Using the contextual option "%s" of the generic transformer "%s" as "{{ %s }}", with underscores instead of dashes, is deprecated: write "{{ %s }}". The dashes of the contextual option codes were replaced by underscores before 5.9, the former name will not be replaced in v6.0.',
+                $this->deprecatedContextualOptions[$formerName],
+                $this->transformerCode,
+                $formerName,
+                $this->deprecatedContextualOptions[$formerName],
+            );
+        }
+    }
+
+    /**
+     * A contextual option whose code has a dash can also be given by its former name, with underscores (deprecated).
+     *
+     * Deprecated since 5.10, will be removed in v6.0.
+     *
+     * @param array{required: bool, default: mixed, default_is_null: bool} $optionConfig
+     */
+    private function configureFormerContextualOption(OptionsResolver $resolver, string $option, string $formerName, array $optionConfig): void
+    {
+        $resolver->setDefined($formerName);
+        $transformerCode = $this->transformerCode;
+        // Given by its code, by its former name, or the default value
+        $resolver->setDefault($option, static function (Options $options) use ($option, $formerName, $optionConfig, $transformerCode): mixed {
+            if ($options->offsetExists($formerName)) {
+                trigger_deprecation(
+                    'cleverage/process-bundle',
+                    '5.10',
+                    'Using the contextual option "%s" of the generic transformer "%s" by the name "%s", with underscores instead of dashes, is deprecated: use "%s". The dashes of the contextual option codes were replaced by underscores before 5.9, the former name will not be accepted in v6.0.',
+                    $option,
+                    $transformerCode,
+                    $formerName,
+                    $option,
+                );
+
+                return $options[$formerName];
+            }
+            if (null !== $optionConfig['default'] || $optionConfig['default_is_null']) {
+                return $optionConfig['default'];
+            }
+            if ($optionConfig['required']) {
+                throw new MissingOptionsException(\sprintf('The required option "%s" is missing.', $option));
+            }
+
+            return null;
+        });
+    }
+
+    /**
+     * The strings of the transformer options, keys and values, where "{{ code }}" is replaced.
+     *
+     * @param array<int|string, mixed> $values
+     *
+     * @return list<string>
+     */
+    private static function getStrings(array $values): array
+    {
+        $strings = [];
+        foreach ($values as $key => $value) {
+            $strings[] = (string) $key;
+            if (\is_array($value)) {
+                $strings = [...$strings, ...self::getStrings($value)];
+            } elseif (\is_string($value)) {
+                $strings[] = $value;
+            }
+        }
+
+        return $strings;
+    }
 }