feat(rules): configurable controllerNamespacePrefixes on the three controller-scoped rules (WR-0283)

[Goosterhof]

What & why

The three controller-scoped rules — ForbidEloquentMutationInControllersRule, EnforceCurrentUserAttributeRule, ForbidResourceWrappedInJsonResponseRule — each hardcoded private const CONTROLLER_NAMESPACE_PREFIX = 'App\Http\Controllers'. emmie ships controllers under App\Http\Client\Controllers (4) + App\Http\Admin\Controllers (9), so their inline Eloquent mutations / $request->user() / resource-wraps were rule-invisible (surfaced by the emmie WR-0275 migration pilot). ForbidEloquentMutationInControllersRule's own docblock already prescribed the fix: "lift this into a controllerNamespacePrefixes."

Fleet survey (2026-07-02): emmie is the only consumer with sub-namespaced controllers — kendo/ublgenie/entreezuil/codebook use canonical App\Http\Controllers, already fully covered.

Change

• New optional PHPStan parameter controllerNamespacePrefixes (default ['App\Http\Controllers']), wired through extension.neon on all three rules — mirrors the formRequestBaseClass precedent. The namespace gate now matches when the class namespace starts with any configured prefix.
• Consumers with sub-namespaced controllers enroll them in their phpstan.neon; everyone else is unaffected.

Versioning — backward-compatible MINOR

Default ['App\Http\Controllers'] reproduces the prior str_starts_with behaviour byte-for-byte (kendo's App\Http\Controllers\Central\* still flags under default) ⇒ zero new errors in any consumer at the default. New violations appear only when a consumer opts a divergent namespace in. Same shape as v0.6.0's formRequestToDtoExemptClasses.

Tests / gates

• +9 tests (124 → 133): per rule, a sub-namespaced-controller fixture proving CLEAN-under-default + FLAGGED-when-configured, plus a container-resolved test exercising the shipped NEON default + %controllerNamespacePrefixes% wiring (the guard against a NEON double-backslash no-op regression).
• All pre-existing fixtures/tests green (canonical + Central\* still flag under default).
• composer test 133/199 · phpstan level max clean · Pint clean · coverage 88.61% · Infection MSI 84.72% (zero escaped mutants in the new gate code) · audit clean.

Downstream

emmie opt-in tracked as WR-0291 (enroll its two sub-namespaces + baseline-absorb the ~32 surfaced mutations, folding into the WR-0275 migration campaign). EnforceCurrentUserAttribute surfaces 0 on emmie (already #[CurrentUser]); ForbidResourceWrapped a small surface.

🤖 Generated with Claude Code

[jasperboerhof]

Town Crier Review · 9/10 · PASS · 🔎 Independent

phpstan-warroom-rules #48 · AC anchor: PR description (no reachable board) · head 78ecd57f41 · via the town-crier bus (request #220)

Tip

Reviewed a contract-package feature that lifts the hardcoded App\Http\Controllers gate into a shared configurable controllerNamespacePrefixes parameter across all three controller-scoped rules; verified the default is byte-for-byte identical (single-element list loop == prior single str_starts_with), that no fourth rule still hardcodes the prefix (CONTROLLER_NAMESPACE_PREFIX fully removed; remaining getNamespace() rules are Action-scoped), that all three rules are wired in extension.neon with a listOf(string()) schema, and that the new sub-namespace fixtures genuinely fire via the tests/Fixtures/ classmap autoload rather than being vacuous. The one sharp edge — NEON list params replace, so a consumer overriding the list must re-include the canonical prefix or silently lose coverage — is standard PHPStan behavior and correctly documented in the README recipe; CI is pending (8.4/8.5), not red.

No findings — clean against the review checklist.

[jasperboerhof]

Auto-approved — Town Crier verdict PASS @Head, CI green, no open MAJOR+ thread. Our approval is our independent vote (approve-alongside): a peer's review / CHANGES_REQUESTED never withholds it — we verify every blocker ourselves, and a real one drops our own verdict below PASS. See the verdict comment + inline notes.

[Goosterhof]

✅ Approve-worthy

0 blockers · 0 concerns · 1 nit · 2 praise · 0 inline

CI green (8.4/8.5). Bus thread: dispatch posted an independent PASS at 14:16 (no findings, correctly flagged the standard NEON-list-replace semantics as documented, not a defect); Jasper's harness auto-approved on that verdict. I independently re-derived the same result — confirming, not just deferring to, dispatch's read.

Lifts the hardcoded App\Http\Controllers gate on the three controller-scoped rules (ForbidEloquentMutationInControllersRule, EnforceCurrentUserAttributeRule, ForbidResourceWrappedInJsonResponseRule) into a shared configurable controllerNamespacePrefixes parameter, mirroring the formRequestBaseClass/resourceDataBaseClass precedent — closes the emmie sub-namespace blind spot (WR-0283).

Verification

• Default-preservation claim confirmed: all three rules replace str_starts_with($ns, self::CONST) with a foreach-any-prefix loop over a single-element default array — byte-identical match set at the default.
• "No fourth rule still hardcodes the prefix" claim confirmed by direct grep of src/Rules/*.php — CONTROLLER_NAMESPACE_PREFIX is fully gone from the tree; the only other namespace-scoped rules (EnforceActionTransactionsRule, ForbidDatabaseManagerInActionsRule) gate on App\Actions, unaffected.
• extension.neon wiring confirmed on all three rules' service definitions + parametersSchema: listOf(string()).
• Container-resolution tests (testRuleResolvesFromExtensionNeonAndFiresOnDefaultPrefix) correctly close the gap a constructor-default-only test would miss — a NEON single/double-backslash quoting slip would silently no-op the whole rule for every default consumer, and only an extension.neon-loaded test catches that class of regression.
• Constructor shape (private array $controllerNamespacePrefixes = ['App\Http\Controllers']) matches the existing formRequestBaseClass/resourceDataBaseClass single-param precedent style — no stylistic drift.

Nit

• The constructor property is typed bare array (phpdoc-only list<string>) on all three rules — matches existing precedent ($formRequestBaseClass is typed string, so there's no established list<string>-native pattern here either), so this isn't a regression, just worth tightening to array<int, string>/list<string> via a phpstan-level self-hint if the package ever raises its own bar on iterable value types.

Praise

• The testRuleResolvesFromExtensionNeonAndFiresOnDefaultPrefix gate per rule — pinning the shipped NEON default, not the PHP constructor default, closes exactly the failure class this kind of config-lift usually ships with.
• CHANGELOG entry states the versioning call explicitly (backward-compatible MINOR, contrasted against the v0.5.0 candidate-major shape) — keeps the release-decision reasoning auditable instead of asserted.

Automated war-room agent review — posted because this PR carries the Agent Review Requested label.