Review main Merged Breaking

91231[!!!][TASK] Modernize backend template components API

Oli Bartsch CR +2 V +2 Nightmare +2230 −1047 updated 10/24/25, 18:17

Commit message

In our ongoing effort to improve the overall UI,
the backend template components API (ButtonBar,
Menu system, and related components) are modernized
with strict typing, improved interfaces, and type-safe
data structures to provide a more robust and
developer-friendly API.

This will help us and also extension authors to add
functionality in the backend in a consistent and
standardized way.

API improvements:

* Introduce ComponentInterface as unified parent for
  ButtonInterface and DropDownItemInterface with strict
  contracts: isValid(): bool, getType(): string,
  render(): string
* Replace SplitButton::getButton() array with getItems()
  returning type-safe SplitButtonItems DTO (eliminates
  magic array keys)
* Introduce ComponentFactory as central factory for all
  button creation, providing both pre-configured common
  buttons (back, close, save, refresh) and basic button
  creation methods (create*() methods)
* Deprecate ButtonBar::make*() methods in favor of
  ButtonFactory::create*() methods for cleaner
  separation of concerns (ButtonBar manages organization,
  ComponentFactory handles creation)
* Enforce strict typing on PositionInterface
  (getPosition(): string, getGroup(): int)
* Standardize icon handling with consistent nullable
  Icon types across all button implementations
* Remove invalid parameters from MenuItem::isValid()
  and Menu::isValid()
* Use static return types in abstract classes for
  better inheritance
* Add comprehensive API documentation with usage
  examples to all component classes

ComponentFactory uses a fluent interface rather than
parameters to maintain consistency with TYPO3 patterns,
accommodate diverse button types with different properties,
avoid code duplication, and keep the factory simple.
Pre-configured methods handle common cases while
custom buttons use clear, chainable setters.

Extensions implementing or extending backend template
component interfaces need to add proper return type
declarations to satisfy strict typing.

Review

  • Code review CR +2 Done
    • Oli Bartsch +2
    • Garvin Hicking +1
    • Sven Liebert +1
  • Verified V +2 Done
    • Oli Bartsch +2
    • Garvin Hicking +1
    • Sven Liebert +1
    • core-ci +1 CI

Issues 1

Files 38

Show 18 more files

Review log 3649

Show 1824 earlier messages
  1. Oli Bartsch uploaded patch set 1 10/23/25, 22:45

  2. core-ci voted on patch set 1 V -1 10/23/25, 22:52 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87451

  3. Oli Bartsch uploaded patch set 2 V -1 10/24/25, 06:33

  4. core-ci voted on patch set 2 V +1 10/24/25, 06:41 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87466

  5. Garvin Hicking wrote 10/24/25, 08:57

    Topic set to buttonbar
  6. Benni Mack commented on patch set 2 10/24/25, 09:18

    ButtonBar.php:182

    we should deprecate these methods in the next patch in favor of newly created Factory. cc @garvin@hick.ing
  7. Oli Bartsch uploaded patch set 3 V +1 10/24/25, 09:24

  8. core-ci voted on patch set 3 V -1 10/24/25, 09:33 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87478

  9. Oli Bartsch uploaded patch set 4 V -1 10/24/25, 09:49

  10. core-ci voted on patch set 4 V +1 10/24/25, 09:56 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87481

  11. Oli Bartsch uploaded patch set 5 V +1 10/24/25, 09:58

  12. core-ci voted on patch set 5 V +1 10/24/25, 10:05 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87482

  13. Oli Bartsch commented on patch set 5 10/24/25, 10:13

    ButtonBar.php:182 Reply

    Done
  14. Garvin Hicking commented on patch set 5 10/24/25, 12:26

    ButtonFactory.php:140

    Just to note this here, we could use named parameters here for this factory to make integration much shorter: ``` public function createInputButton( string $name = '', string $value = '', string $label = '', string $iconIdentifier = '', IconSize $iconSize = IconSize::SMALL ): InputButton { $button = $this->createLinkButton(); if ($iconIdentifier) { $button->setIcon($this->iconFactory->getIcon($iconIdentifier, $iconSize)) } if ($name) { $button->setName($name); } if ($value) { $button->setValue($value); } if ($label) { $button->setTitle($this->getLanguageService()->sL($label)); } return $button; } ``` In Bennis follow-up patch https://review.typo3.org/c/Packages/TYPO3.CMS/+/91116 this would allow RecordList/FileList to do things like: ``` $button = $this->ButtonFactory->createAction(name: 'Action', iconIdentifier: 'save-action'); ```
  15. Garvin Hicking commented on patch set 5 10/24/25, 12:50

    ButtonBar.php:187

    We could utilize the factory here as well?

    ButtonBar.php:202

    EventDispatcherInterface could use constructor DI here too

    ShortcutButton.php:166

    Use DI for this?

    ShortcutButton.php:219

    Would it be worth to also migrate the service-related makeInstance calls (PageRenderer, UriBuilder) to constructor DI, or side-effects?

    DropDownRadio.php:59

    Use constructor DI for this here?

    DropDownToggle.php:21

    unused, can be removed (probably due to the example code?)

    InputButton.php:92

    Would `static::class` be more compliant to the fluent API return types?

    SplitButton.php:102

    `@return this` could be removed

    SplitButton.php:219

    Could be removed, automatic inference

    DocHeaderComponent.php:111

    ```suggestion public function setMetaInformation(array $metaInformation): void ```

    DocHeaderComponent.php:122

    Put into constructor DI?

    Action.php:78

    Just to be sure, we cannot use DI for this IconFactory because the inject* Methods do not work on non-autoconfigured objects, right?
  16. Oli Bartsch uploaded patch set 6 V +1 10/24/25, 12:58

  17. Oli Bartsch commented on patch set 6 10/24/25, 12:59

    ButtonFactory.php:140 Reply

    While implementing this, I actually decided against this. I have added the reasons to the commit message and also mention them in the rst.
  18. Garvin Hicking commented on patch set 6 10/24/25, 13:02

    FullyRenderedButton.php:70

    Use static::class here?

    LinkButton.php:79

    (similar to the other notes, static::class?)

    SplitButton.php:145

    I think we should throw the runtimeexception before `new SplitButtonItems` after that `if` above for clarity.

    MenuItem.php:65

    ```suggestion public function setActive(bool $active): static ```
  19. core-ci voted on patch set 6 V +1 10/24/25, 13:07 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87499

  20. Garvin Hicking commented on patch set 6 10/24/25, 13:11

    ButtonFactory.php:140 Reply

    Hm, I don't see it like that. I think we could offer this on-top and optionally. Especially dealing with getLanguageService() and iconFactory is really ugly. Compare: ``` $moduleLink = $this->ButtonFactory->createLink( name: 'Action', iconIdentifier: 'save-action', iconSize: IconSize::SMALL, label: 'some.label', data: ['customAttribute' => 'customValue'], hrefRoute: ['file_edit', $parameter] ); ``` with: ``` $moduleLink = $this->buttonFactory->createLinkButton() ->setHref((string)$this->uriBuilder->buildUriFromRoute('file_edit', $parameter)) ->setDataAttributes(['customAttribute' => 'customValue']) ->setShowLabelText(true) ->setTitle($this->getLanguageService()->sL('some.label')) ->setIcon($this->iconFactory->getIcon('file-edit', IconSize::SMALL)); ``` That is a monster with several dependencies you would need to inject. The arguments could all be left empty and then you receive an object that can still use fluent API if you prefer...
  21. Garvin Hicking commented on patch set 6 10/24/25, 13:13

    ButtonFactory.php:140 Reply

    Note: I think this discussion does not need to take place in this patch here. We could merge this one and shift the discussion to a later time/patch.
  22. Garvin Hicking commented on patch set 6 10/24/25, 13:19

    Feature-107824-ComponentFactoryForBackendComponents.rst:14

    Please reference the FQCN here, this makes the docs create proper references

    Feature-107824-ComponentFactoryForBackendComponents.rst:55

    ```suggestion The corresponding :php:`ButtonBar::make*()` methods are now deprecated. ```

    Feature-107824-ComponentFactoryForBackendComponents.rst:161

    Maybe an alternative route to satisfy both needs is that we introduce more setters like: ``` setIconIdentifier() setLabel() ``` and those could internally use the DI components, and allow shorthand fluent API usage? Thank you for writing up such a detailed rationale. I should have read that before only the commit message, I'm sorry.
  23. Oli Bartsch uploaded patch set 7 V +1 10/24/25, 13:24

  24. Oli Bartsch commented on patch set 6 10/24/25, 13:24

    ButtonBar.php:187 Reply

    Done

    ButtonBar.php:202 Reply

    Done

    ShortcutButton.php:166 Reply

    Done

    ShortcutButton.php:219 Reply

    Done

    ButtonFactory.php:140 Reply

    My main problems are (from rst): A parameter-based approach would require duplicating all button-specific configuration knowledge in both the button classes and the factory methods. This creates a maintenance burden where changes to a button's properties must be reflected in multiple locations. Different button types have vastly different configuration requirements. For example, InputButton needs name/value/form attributes, LinkButton needs href attributes, DropDownButton needs items, and SplitButton needs primary/secondary actions.

    DropDownRadio.php:59 Reply

    Done

    DropDownToggle.php:21 Reply

    Done

    FullyRenderedButton.php:70 Reply

    Done

    InputButton.php:92 Reply

    Done

    LinkButton.php:79 Reply

    Done

    SplitButton.php:102 Reply

    Done

    SplitButton.php:145 Reply

    Done

    SplitButton.php:219 Reply

    Done

    DocHeaderComponent.php:111 Reply

    Done

    DocHeaderComponent.php:122 Reply

    Done

    MenuItem.php:65 Reply

    Done

    Action.php:78 Reply

    Yes. Would result in ``` Cannot autowire service "TYPO3\CMS\Backend\Template\Components\MultiRecordSelection\Action": argument "$name" of method "__construct()" is type-hinted "string", you should configure its value explicitly. ```
  1. Oli Bartsch uploaded patch set 8 10/24/25, 13:33

  2. Oli Bartsch commented on patch set 8 10/24/25, 13:34

    Feature-107824-ComponentFactoryForBackendComponents.rst:14 Reply

    Done

    Feature-107824-ComponentFactoryForBackendComponents.rst:55 Reply

    Done

    Feature-107824-ComponentFactoryForBackendComponents.rst:161 Reply

    This would be a good approach. We would then however talk about injecting services in "DTOs", which is what I would call the button classes.
  3. core-ci voted on patch set 7 V -1 10/24/25, 13:34 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87501

  4. Oli Bartsch uploaded patch set 9 10/24/25, 13:40

  5. core-ci voted on patch set 8 V -1 10/24/25, 13:43 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87502

  6. Oli Bartsch uploaded patch set 10 10/24/25, 13:44

  7. Oli Bartsch commented on patch set 10 10/24/25, 13:45

    ShortcutButton.php:166 Reply

    Reverted as this does not properly work and such optimizations can be done separately.

    ShortcutButton.php:219 Reply

    Reverted as this does not properly work and such optimizations can be done separately.

    DropDownRadio.php:59 Reply

    Reverted as this does not properly work and such optimizations can be done separately.
  8. core-ci voted on patch set 9 V -1 10/24/25, 13:50 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87503

  9. core-ci voted on patch set 10 V +1 10/24/25, 13:52 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87504

  10. Garvin Hicking commented on patch set 10 CR +1 V +1 10/24/25, 13:59

    Thank you! Really good stuff. You saved me several hours of work with this :-D

    ButtonFactory.php:140 Reply

    Acknowledged

    Feature-107824-ComponentFactoryForBackendComponents.rst:161 Reply

    Understood. Let's resolve this and face it in a distinct patch about this.
  11. Sven Liebert commented on patch set 10 CR +1 V +1 10/24/25, 14:12

    Code looks nice now :) Thank you!
  12. Oli Bartsch uploaded patch set 11 CR +1 V +1 10/24/25, 14:28

  13. Oli Bartsch updated the commit message in patch set 12 10/24/25, 14:31

  14. Sven Liebert voted on patch set 12 CR +1 V +1 10/24/25, 14:32

  15. core-ci voted on patch set 11 V +1 10/24/25, 14:38 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87510

  16. core-ci voted on patch set 12 V +1 10/24/25, 14:41 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87511

  17. Oli Bartsch uploaded patch set 13 CR +1 V +1 10/24/25, 14:48

  18. Sven Liebert voted on patch set 13 CR +1 V +1 10/24/25, 14:51

  19. Garvin Hicking commented on patch set 13 CR +1 V +1 10/24/25, 14:55

    Shiny!
  20. core-ci voted on patch set 13 V +1 10/24/25, 14:56 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/87516

  21. Markus Klein commented on patch set 12 10/24/25, 15:03

    ButtonBar.php:130

    since this is a breaking change anyway: move these to an enum too?
  22. Garvin Hicking commented on patch set 13 10/24/25, 15:54

    ButtonBar.php:130 Reply

    The breaking changes are kind of "soft" as most of the API can be used without shuffling your feet. Replacing tbis one would requore code changes though. Elias also did a similar patch for this: https://review.typo3.org/c/Packages/TYPO3.CMS/+/89733 and I think this would make it harder for dual-core-version usages.
  23. Oli Bartsch commented on patch set 13 CR +2 V +2 10/24/25, 16:37

    ButtonBar.php:130 Reply

    I did not migrate this to enum intentionally, because those constants are basically used everywhere and in so many custom extensions, dealing with backend modules. There is IMO not that much benefit. However I would not block any patch doing this, but I don't see it here.
  24. Oli Bartsch merged patch set 14 10/24/25, 16:37

  25. Markus Klein commented on patch set 14 10/24/25, 18:17

    ButtonBar.php:130 Reply

    Roger. ✔