Breaking: #107823 - Strict typing and API cleanup in backend template components

Description

The backend template components system (buttons, dropdown items, and menus) has been modernized with strict type hints, consistent return types, and improved architecture to enhance type safety and developer experience.

Impact

Extensions that implement or extend backend template components need to verify their type declarations and update usage of changed methods.

New ComponentInterface

A new ComponentInterface has been introduced as the parent interface for both ButtonInterface and DropDownItemInterface. This unifies the common contract for all renderable backend components.

Both interfaces now extend ComponentInterface which defines:

isValid(): bool
getType(): string
render(): string

Custom implementations of ButtonInterface or DropDownItemInterface will cause a TypeError if these return types are missing.

PositionInterface enforced

The PositionInterface now enforces strict type hints:

getPosition(): string
getGroup(): int

This interface allows buttons to define their own fixed position and group, which will automatically override the position/group parameters passed to ButtonBar::addButton().

Icon nullability

Icons are now consistently nullable across all button types. The AbstractButton::$icon property and related getter/setter methods now use ?Icon instead of Icon.

This affects classes extending AbstractButton (LinkButton, InputButton, SplitButton).

Note

While icons are technically optional at the type level, validation methods may still require icons for buttons to be considered valid.

Method signature changes

Several methods now have stricter parameter types or modified signatures:

MenuItem::isValid() and Menu::isValid() no longer accept parameters
AbstractDropDownItem::render() now declares string return type
Various setter methods now require proper type hints for their parameters

Return type consistency

Abstract classes use static return types for better inheritance support, while concrete implementations may use self or static depending on extensibility requirements.

SplitButton API improvement

The SplitButton::getButton() method has been replaced with getItems() which returns a type-safe SplitButtonItems DTO instead of an untyped array.

Old (removed):

public function getButton(): array  // Returns array with magic keys 'primary' and 'options'

New:

public function getItems(): SplitButtonItems  // Returns typed DTO

The SplitButtonItems DTO provides:

public readonly AbstractButton $primary - The primary action button
public readonly array $options - Array of option buttons

This change improves type safety and prevents runtime errors from accessing non-existent array keys.

Affected Migration

Extension authors should:

Verify custom button implementations have correct return types on interface methods
Check custom classes extending abstract buttons use appropriate return types
Update isValid() calls on MenuItem and Menu objects (remove the parameter)
Handle nullable icons when working with button getIcon() methods

Example: Implementing ButtonInterface

// Before
class CustomButton implements ButtonInterface {
    public function isValid() { ... }
    public function render() { ... }
    public function getType() { ... }
}

// After
class CustomButton implements ButtonInterface {
    public function isValid(): bool { ... }
    public function render(): string { ... }
    public function getType(): string { return static::class; }
}

Example: Working with MenuItem/Menu

// Before
if ($menuItem->isValid($menuItem)) { ... }

// After
if ($menuItem->isValid()) { ... }

Example: Nullable icons

// Handle nullable icon return
$icon = $button->getIcon();  // Now returns ?Icon
$html = $icon?->render() ?? '';

Example: Using SplitButton with typed DTO

If you were directly accessing the getButton() method:

// Before
$items = $splitButton->getButton();
$primary = $items['primary'];  // Magic string key
$options = $items['options'];  // Magic string key

// After
$items = $splitButton->getItems();
$primary = $items->primary;  // Type-safe property access
$options = $items->options;  // Type-safe property access