TransformerTrait: document that any #suffix is accepted on transformer codes #236

Description

To use the same transformer several times in a transformers list (YAML keys must be unique), a suffix starting with # can be added to the transformer code. The documentation and the docblock only mention a numeric suffix (callback#1, callback#2), and the regex of TransformerTrait::getCleanedTransfomerCode() suggests so:

preg_match('/([^#]+)(#[\d]+)?/', $transformerCode, $parts);

But the regex is not anchored, so any suffix is actually accepted: callback#foo or callback#bar-baz are applied as callback, and even an empty suffix (callback#) is.

Reproduction

transformers:
    'callback#upper': { callback: strtoupper }
    'callback#reverse': { callback: strrev }
# 'abc' => 'CBA'

Tested on main (ba31efc), PHP 8.5, Symfony 7.4. No configuration of the cleverage bundles nor of the demo project uses a non-numeric suffix.

Proposed fix

A named suffix is useful to describe each step (callback#trim, callback#reverse), and restricting the suffixes to digits would break the configurations using them. So:

• document that any non-empty suffix is accepted (docblock and docs/reference/traits/transformer_trait.md, with a named suffix in the example);
• make the regex explicit: /^([^#]+)#.+$/ (the part before the first # is used as the transformer code if it is registered, otherwise the whole code is looked up);
• add tests for TransformerTrait suffixes.

Requirements

• Documentation updates
  • Reference
  • Cookbooks
  • Changelog
• Unit tests

Breaking changes

None in practice: numeric and named suffixes keep working. Only an empty suffix (callback#), accepted by accident, now throws a MissingTransformerException.