[rubenvdlinde]

What changed

This replaces #1077 with the same split plus one more step: the role widget filter (AllowedWidgetFilter) and the calendar window parsing (CalendarRangeParser) live in two small final classes beside the controller, which keeps WidgetApiController under the class-length ceiling of phpmd.xml.

Nine WidgetApiController units read as named steps. Route actions keep their signatures, and every guarded action still carries its literal guard (requireAction($user, '<key>') or actionRefusal(...) / a deny* call), which both the guard golden and the action-seed coverage scan read.

• listAvailable → denyListAvailable → AllowedWidgetFilter::filter (no user or nothing configured: every widget; else the widgets with an allowed id, in order).
• addWidget keeps its guard and depth check, then hands the layout to createPlacement, which addTile now shares (201, the widget quota as 409, the generic error) instead of two copies of the same catch blocks; contentToPersist replaces the inline content branch.
• denyAddWidget keeps the session guard, then denyWidgetChoice (isBlankId, mayAddWidget: dashboard permission, then the role-feature profile, in that order).
• addTile → mayAddTo, addTileFromRequest; updatePlacement → denyPlacementUpdate (mayStyle, acknowledgement, container depth, in the original order) → updatedPlacement; denyAcknowledgementChange → touchesAcknowledgement.
• newsItems → effectiveNewsLimit → newsFor (limit range, then view permission); calendarEvents → calendarEventsIn (placement lookup, then view permission) → calendarEventsOf; resolveCalendarRange keeps its answer shape and asks CalendarRangeParser (required bounds, dates, order, one-year cap, the same three messages).

Allowed and refused outcomes are unchanged, every refusal has the same status and body, and every check still runs before the call it guards.

Characterisation tests

tests/Unit/Controller/WidgetApiControllerActionsGoldenTest.php was committed first, against the old code, and passes before and after. It pins what each action answers once its caller guard has passed: the available-widget filter (no user, nothing configured, a configured list), every add-widget refusal (missing or empty id, dashboard permission, role filter not asked after a dashboard refusal, container depth and other depth errors) and the exact layout and content handed to the service with the quota / generic mappings, every tile and placement-update outcome (style permission, acknowledgement fields with and without permission, depth, service error), the news limit bounds and default, and every calendar range outcome including the one-year cap, an unknown placement, a non-viewer and a failing calendar backend. Mutation check: disabling the role-feature check on the old code turned the add-widget golden red; restored before committing. The caller guards are pinned by the existing WidgetApiControllerGuardGoldenTest, which passes unchanged.

What ran

• vendor/bin/phpunit -c phpunit.xml --no-coverage tests/Unit: 2774 tests OK (13 skipped, as on development), including the action-seed coverage scan.
• vendor/bin/phpcs and vendor/bin/phpstan analyse on the touched lib files: clean.
• vendor/bin/phpmd on the touched lib files: one finding, TooManyMethods (37 methods against a limit of 25), the cost of turning long methods into named private steps; composer phpmd is already red on development for other classes.

Figures (touched files lib/Controller/WidgetApiController.php, AllowedWidgetFilter.php, CalendarRangeParser.php)

	before	after
units over complexity 5	9 units, 300 lines	0
units over 15 lines of code	14 units, 410 lines	9 units, 196 lines
units over 2 parameters	3 units, 93 lines	3 units, 60 lines
duplicated windows inside the controller	8	0

addWidget (six route parameters), addTile and updatePlacement (the literal guard) stay a little over 15 lines. AllowedWidgetFilter depends on RoleFeaturePermissionService (already used by the controller); only the controller depends on the two new classes. App-wide: unit complexity 4.02 → 4.16, unit size 3.40 → 3.43, duplication 4.54 → 4.56, unit interfacing 3.14 → 3.15.

Maintainability floor: compare against development holds.

AI-assisted: prepared with Claude Code (claude-opus-5-5); reviewed by a maintainer before merge.

---

Generated by Claude Code