Issue Feature New Orphaned Good first issue

#109613 Add explicit ordering mechanism for Site Settings categories

Daniel Kleiner 04/17/26, 05:25 updated 04/21/26, 11:23

Description

  1. Feature Request: Add explicit ordering for Site Settings categories

Tracker: Feature
**Subject:** Add explicit ordering mechanism for Site Settings categories
**Category:** Site Handling, Site Sets & Routing
**TYPO3 Version:** 13.4 / main (v14)

—-

## Problem

The order of categories in the Site Settings Editor (introduced in #104794) is determined implicitly by the topological loading order of Site Sets. There is no way to explicitly control the display order.

This creates a poor editorial experience:

- Loading order != editorial priority. Extensions like `typo3/fluid-styled-content` load early (because others depend on them) and appear at the top — even though admins rarely touch those settings. Project-specific settings (branding, colors) that are edited frequently end up buried below.
- Fragile ordering. Adding or removing an extension can shift category positions without any deliberate change, making the UI feel unpredictable.
- No clean workaround. The only lever is to add artificial Set dependencies solely to influence display order. This misrepresents actual dependencies and can cause unintended TypoScript loading side effects.

## Proposed solution

Add an optional `order` (integer) property to `CategoryDefinition`:

```yaml
categories:
myextension:
label: ‘My Extension’
order: 20
```

**Sorting rules:**
- Categories with an explicit `order` are sorted ascending.
- Categories without `order` retain current insertion order (full backward compatibility).
- Subcategories inherit sorting within their parent scope.

## Implementation scope

Minimal and fully backward-compatible:

1. Add `public ?int $order = null` to `CategoryDefinition` and `Category`.
2. In `CategoryAccumulator::getCategories()`, apply `usort()` on the final array: ordered categories first (ascending), then unordered ones in current insertion order.
3. Support `order:` key in `settings.definitions.yaml` parsing in `YamlSetDefinitionProvider`.

Estimated: ~30 lines of code, no database changes, no breaking changes.

## Example

A typical project wants this display order:

Position Category Reason
—- —- —-
10 Brand & Colors Edited most frequently
20 Powermail Project-critical form settings
30 Powermail Enhancer Related to Powermail
40 MailChimp Rarely changed after setup
50 SEO Occasional adjustments
99 Fluid Styled Content Almost never touched

Today this requires artificial Set dependencies. With `order`, each extension declares its preferred position — deterministic and transparent.

Reviews 0

No change resolves or names this issue in its commit message, and no comment links one.

Fix this issue

Start the commit message of your patch with this. Add what the patch does, and the versions it goes to in "Releases:". How to create a patch

Commit message
[FEATURE] Add explicit ordering mechanism for Site Settings categories Resolves: #109613 Releases: main