#279 - Mark the classes not meant to be extended @final and the infrastructure classes @internal

[njoubert-cleverage]

Description

v5 step of #279 (Symfony BC promise): define the public API with @final / @internal, giving one minor version of notice before v6.0 turns @final into final. #279 stays open for the v6 step.

Changes

• @final since 5.4 (107 classes): the engine (ProcessManager, ProcessConfigurationRegistry, TransformerRegistry, ContextualOptionResolver), the models (ProcessState, ProcessHistory, SubprocessInstance, ProcessConfiguration, TaskConfiguration, the events, ConstraintLoader, the Filesystem files) and the concrete tasks and transformers. Extending one of them from another package triggers a deprecation with the Symfony DebugClassLoader (symfony/error-handler, debug mode).
• Stay open: the abstract classes (AbstractConfigurableTask, AbstractIterableOutputTask, AbstractCsvTask, AbstractCsvResourceTask, Logger\AbstractLogger…), interfaces, traits, exceptions, and the classes actually extended by other classes of the bundle: FileReaderTask, LineReaderTask, FolderBrowserTask, CsvReaderTask, InputCsvReaderTask, Filesystem\CsvResource. The bridge bundles only extend AbstractConfigurableTask (checked in archive, cache, doctrine, flysystem, rest, soap, ui), and ProcessState is only instantiated by ProcessManager.
• TaskRegistry (Fetch tasks from a service locator instead of the service container (v5 step of #114) #275, not released yet) is directly final.
• @internal (13 classes): CleverAgeProcessExtension, Configuration, the 3 commands, DataQueueEventListener, PhpFunctionProvider, the Monolog processors (AbstractProcessor, ProcessProcessor, TaskProcessor, TransformerProcessor), ProcessLogger and TaskLogger (only injected in ProcessManager). The compiler passes and Unavailable* services already were.
• Already @deprecated classes (InputAggregatorTask, RegistryCompilerPass, CheckSerializerCompilerPass) are left as is.
• PHPStan: with @final, PHPStan reports two return types that are too wide (ProcessState::getContextualizedOptions(): ?array, PregFilterTransformer::transform(): array|string|null). Narrowing them would break the child classes until they are really final, so they are ignored with a @phpstan-ignore return.unusedType comment, to narrow in v6.0.
• Docs: new "Extend the bundle without inheriting its classes" section in the good practices (open classes, alternatives: own task, decoration, events, composition; internal classes). CHANGELOG (Latest).

Checks

955 tests, PHPStan, PHP-CS-Fixer, Rector OK.

Requirements

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

Breaking changes

None: @final / @internal are annotations. Extending a @final class triggers a deprecation; it will be a final class in v6.0 (#279).

🤖 Generated with Claude Code