Repository navigation
Define the public API: mark classes final or internal #279
Description
Description
No class of the bundle is final or @internal (checked on main @ cd7b81f): the whole code base is an extension point, so any refactoring (constructor change, renamed protected method or property) is potentially a breaking change. For instance, the constructors of ProcessManager (#275) and of the registries can only gain optional arguments.
The Symfony BC promise relies on @internal / @final / final to define what is covered.
Proposed fix
- v5 (preparation): add
@finalon the classes that are not meant to be extended, and@internalon the infrastructure classes. The SymfonyDebugClassLoaderthen triggers a deprecation for classes extending them, giving one minor version of notice. - v6: turn
@finalintofinaland keep@internal.
Proposed scope, to be discussed in the PR:
| Kind | Classes | Proposal |
|---|---|---|
| Infrastructure | DependencyInjection\* (extension, configuration, compiler passes), EventListener\*, Logger\*Processor, Command\* |
@internal |
| Engine | ProcessManager, ProcessConfigurationRegistry, TransformerRegistry, ContextualOptionResolver |
final (extension through decoration, events and stop checkers) |
| Concrete tasks and transformers | Task\*, Transformer\* |
final by default; stay open: Abstract* classes, traits, and the ones actually extended (to be listed, e.g. in the bridge bundles) |
| Models / value objects | Configuration\*Configuration, Model\ProcessState, events, exceptions |
case by case |
Requirements
- Documentation updates
- Reference
- Cookbooks
- Changelog
- Unit tests
Breaking changes
Major (v6): extending a class that becomes final, or using an @internal class, is no longer supported. The v5 @final annotations only trigger deprecations.
Activity
#279 - Mark the classes not meant to be extended @Final and the infra…
#279 - Mark the classes not meant to be extended @Final and the infra…
Merge pull request #295 from cleverage/279
njoubert-cleverage commentedon Oct 15, 2026
v5 step done in #295 (merged
4d54b19, released in the next 5.x minor):@final since 5.4on 107 classes: the engine (ProcessManager,ProcessConfigurationRegistry,TransformerRegistry,ContextualOptionResolver), the models (ProcessState,ProcessHistory,SubprocessInstance, the configurations, the events,ConstraintLoader, theFilesystemfiles) and the concrete tasks and transformers.FileReaderTask,LineReaderTask,FolderBrowserTask,CsvReaderTask,InputCsvReaderTask,Filesystem\CsvResource).@internalon 13 infrastructure classes (extension,Configuration, commands,DataQueueEventListener,PhpFunctionProvider, Monolog processors,ProcessLogger,TaskLogger).TaskRegistry(not released before) is alreadyfinal.Remaining for v6.0:
@final since 5.4intofinal(and keep@internal).@phpstan-ignore return.unusedTypebecause narrowing them would break child classes until they are final:ProcessState::getContextualizedOptions(): ?array→arrayPregFilterTransformer::transform(): array|string|null→string|null@phpstan-ignorecomments.#56 - Mark the classes not meant to be extended @Final and the infras…
#57 - Mark the classes not meant to be extended @Final and the infras…
#58 - Mark the classes not meant to be extended @Final and the infras…
#55 - Mark the classes not meant to be extended @Final and the infras…