Statamic Affiliates Laravel Package

Technical Evaluation

Architecture fit. This is a Statamic addon (Laravel-based CMS) that customizes Control Panel navigation. The v0.2.1 change adds a settingsNavParent() contract returning a [section, name] tuple that tells the CP where the addon's settings should live. Architecturally this is a sensible, low-coupling extension point: the addon declares intent, and the host (statamic-brand-context) decides placement. It fits teams that are standardizing CP information architecture across a suite of addons.

Integration feasibility. High. The release explicitly states no migration and no new config key, and the behavior is version-gated on statamic-brand-context >= 1.16. Install is drop-in; older brand-context versions simply ignore the method and preserve the prior layout. This is a well-behaved, backward-compatible enhancement.

Technical risk. Moderate-low, with caveats:

• The package is at 0.x, so the settingsNavParent() signature and tuple shape are not yet a stable public API; expect possible breaking changes before 1.0.
• Behavior divergence across brand-context versions creates two supported layouts in the wild (sub-item vs. shared "Addon-Suite" page), which complicates documentation and QA.
• Navigation collisions are possible if multiple addons declare an overlapping [section, name]; the release does not state collision resolution.
• The return contract is an unstructured tuple; there is no evidence of validation for malformed values.

Key questions.

• What are the minimum supported versions of Statamic and statamic-brand-context? Does the addon function without brand-context installed?
• Does the addon expose its own CP navigation entry, or does it rely on the shared "Addon-Suite" page?
• How are duplicate settingsNavParent() declarations resolved across addons?
• Is settingsNavParent() documented as a public extension point with a stability guarantee?
• What is the intended behavior if the tuple references a section/name that does not exist?

Integration Approach

Stack fit. Laravel + Statamic CP. The feature only matters in environments running statamic-brand-context; without it, or below 1.16, the addon keeps its previous layout. No impact on front-end rendering or data layer.

Migration path. None required. Upgrade the addon via Composer; behavior changes only when brand-context 1.16+ is present. No data migration, no config edits.

Compatibility. Backward compatible by design. Forward path is to upgrade statamic-brand-context to 1.16+ to opt into the new nested settings layout. Mixed-version fleets will show inconsistent CP placement until brand-context is aligned.

Sequencing.

1. Confirm current statamic-brand-context version across environments.
2. Upgrade the addon first (safe, no visual change on old brand-context).
3. Upgrade statamic-brand-context to 1.16+ per environment to activate the new layout.
4. Verify CP navigation in staging before rolling to production, especially if multiple addons share the "Addon-Suite" page.

Operational Impact

Maintenance. Low day-to-day burden, but the 0.x version signals API churn. Budget for re-review of the settingsNavParent() contract on minor bumps until 1.0.

Support. Two layout behaviors coexist depending on brand-context version. Support runbooks and screenshots should cover both the "Einstellungen" sub-item and the shared "Addon-Suite" page to avoid confusion tickets.

Scaling. The shared "Addon-Suite" page is a consolidation point; as addon count grows, that page can become crowded and harder to navigate. Addons with their own navigation avoid this, so placement strategy should be decided per suite.

Failure modes.

• Version skew: brand-context below 1.16 silently retains old layout, which can look like the feature "didn't work."
• Misconfigured tuple: an invalid [section, name] may orphan or misplace settings with no loud error.
• Collision: multiple addons targeting the same parent could produce ambiguous navigation.
• 0.x regression: a future minor release may change the method contract without a major-version signal.

Ramp-up. Low. The change is conceptually simple and self-contained. The main learning curve is understanding the brand-context dependency and the version-gated behavior, which should be captured in a short onboarding note.