TransformerRegistry: require the code tag attribute and remove eager transformer registration (v6 step of #276) #280

Description

v6 step of #276. In v5, #276 loads transformers lazily through a service locator indexed by the code attribute of the cleverage.transformer tag (or #[AsTransformer(code: '...')]). Transformers tagged without code keep being instantiated eagerly through TransformerRegistry::addTransformer(), with a deprecation.

Proposed fix

• The code attribute becomes required on the cleverage.transformer tag: a tagged service without code fails the container compilation with an explicit message (add the attribute or use #[AsTransformer]).

• Remove the eager path: TransformerRegistry::addTransformer() and the method calls added by the compiler pass.

• Remove RegistryCompilerPass if it was deprecated by TransformerRegistry: lazy-load transformers through a service locator indexed by code #276 and is not used elsewhere.

• TransformerRegistry only wraps the locator (getTransformer(), hasTransformer()). Decide whether getTransformers() is kept (it instantiates every transformer and is not used by the bundles) or replaced by a method returning the codes.

• Remove TransformerInterface::getCode() (decided): since TransformerRegistry: lazy-load transformers through a service locator indexed by code #276 (PR #276 - TransformerRegistry: lazy-load transformers through a service locator indexed by code #293) the code of a transformer is given by the tag code attribute / #[AsTransformer], getCode() only duplicates it. Its remaining uses, all removed or replaceable:

  • TransformerRegistry::addTransformer() (eager path, removed above);
  • the check "code of the locator === getCode()" in TransformerRegistry::getTransformer() (removed with the method: there is a single declaration of the code);
  • UnavailableServicesCompilerPass (CheckSerializerCompilerPass: do not fail the container compilation when the serializer is disabled #278) reads it by reflection to keep the code of the replaced transformer: read the code of the tag instead (can be done in v5 already).

  GenericTransformer / UnavailableTransformer (which store their code) can keep a getCode() of their own if useful, outside of the interface.

  BC: harmless for the classes implementing the interface (an extra method), breaking for code calling getCode() on a transformer.

  Deprecate it first, in v5 (5.4, with TransformerRegistry: lazy-load transformers through a service locator indexed by code #276): @deprecated PHPDoc on TransformerInterface::getCode() ("since 5.4, the code is given by the code attribute of the cleverage.transformer tag or by #[AsTransformer], it will be removed from the interface in v6.0"), mention in the CHANGELOG / UPGRADE notes, and stop calling it in the bundle where it is not needed (UnavailableServicesCompilerPass). Note: neither trigger_deprecation() (interface method) nor Symfony's DebugClassLoader (it does not report the methods of an interface marked @deprecated) can give a runtime notice; the deprecation is visible to static analysis (PHPStan phpstan-deprecation-rules) and IDEs only.

• Update the bridge bundles if some transformers still lack the attribute.

Requirements

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

Breaking changes

• Major: transformers tagged cleverage.transformer without a code attribute (deprecated since TransformerRegistry: lazy-load transformers through a service locator indexed by code #276) no longer work.
• Major: TransformerRegistry::addTransformer() is removed (and getTransformers() / RegistryCompilerPass depending on the decisions above).