Statamic Insights Laravel Package

Technical Evaluation

Architecture fit This is a Statamic addon running on Laravel, so it inherits the host application's service provider, config, and Control Panel (CP) navigation conventions. v1.6.0 adds a single declarative hook — settingsNavParent() returning a [section, name] tuple identifying the addon's own CP navigation entry. The important architectural property is that the addon declares intent rather than reaching into another addon's nav tree: the resolution is performed by statamic-brand-context (1.16+), which decides whether the addon's settings render as the sub-item "Einstellungen" under its own entry, or under a shared "Addon-Suite" page for addons that ship no navigation of their own. This is a reasonable, low-coupling extension point, but it is an implicit contract — the method is meaningful only in the presence of a compatible consumer.

Integration feasibility High. The release explicitly states no migration and no new config key, and older brand-context versions ignore the method and retain the previous layout. That makes the upgrade a composer update plus a cache clear, with the only observable change being the placement of settings pages in the CP. Two behavioral paths must be validated: (a) brand-context ≥ 1.16 present → new placement; (b) brand-context < 1.16 or absent → unchanged placement.

Technical risk Low overall, but not zero. Principal risks:

• Silent degradation. On brand-context < 1.16 the method is ignored with no warning. Nothing breaks, but the expected UX does not appear and there is no signal why — a classic "works as designed, looks like a bug" support case.
• Duplicate navigation. If the addon also registers its own settings entry independently, the new sub-item may duplicate it. Needs verification, not assumption.
• Localization. The documented label "Einstellungen" is German. If it is hardcoded rather than translated, non-German installs get an inconsistent CP.
• Version skew. Behavior depends on a peer addon's version, so the addon is no longer independently testable for nav correctness.
• Permissions. The shared "Addon-Suite" page aggregates multiple addons' settings; if per-addon permissions differ, visibility/entitlement semantics could blur.

Key questions

1. Is statamic-brand-context declared as a hard or soft (suggest/dev) dependency in composer.json, and is a minimum version constrained?
2. Is settingsNavParent() a documented public interface with a stated return contract, or an internal convention?
3. Does the addon still register a fallback CP nav/settings entry when brand-context is absent, and is that path tested?
4. Is "Einstellungen" translatable, or a hardcoded string?
5. Does the addon's own nav entry carry permission gating, and how does that interact with the shared Addon-Suite page?
6. Is a malformed return value (non-tuple, null section) handled defensively by the consumer, or does it throw?

Integration Approach

Stack fit Standard Laravel/Statamic composer dependency; no new runtime services, no queue, no storage. The change lives entirely in the CP navigation layer and therefore touches no application data path. It fits cleanly into an existing Laravel deployment pipeline (build → composer install → cache warm).

Migration path No migration and no config key, so the path is: bump the package, then clear caches. Statamic caches navigation and the Stache, so php artisan cache:clear and php artisan statamic:stache:clear should be part of the deploy step, otherwise the nav change may not surface and will look like a failed upgrade.

Compatibility Treat this as a 2×3 compatibility matrix and test the cells rather than the package in isolation:

Pin statamic-brand-context to ≥ 1.16 in environments where the new placement is expected (notably staging and any environment used to produce screenshots or training material), so documentation does not drift from production.

Sequencing

1. Upgrade the addon alone in staging with brand-context at its current version — confirm no change and no errors (proves the ignore path).
2. Upgrade brand-context to 1.16+ in staging — confirm nav placement, absence of duplicates, localized label, and permission behavior per role.
3. Re-capture CP screenshots and update admin/support documentation.
4. Roll to production in the same order, with cache clears after each step.

Operational Impact

Maintenance Negligible code maintenance — one method, no schema, no config surface. The real maintenance cost is documentation: internal admin guides, onboarding material, and screenshots of the CP settings location are now conditional on a peer addon's version.

Support Support surface grows slightly in a predictable way. Expect "our settings moved" / "the settings page disappeared" tickets immediately after any brand-context upgrade. Mitigation: add the installed statamic-brand-context version to the standard bug-report intake, and give first-line support a one-line decision tree (brand-context < 1.16 → old layout is correct behavior).

Scaling No impact. Nav resolution executes per CP request only; cost is trivial relative to CP rendering and is invisible to front-end traffic or queue throughput.

Failure modes

• Silent no-op on older brand-context — most likely failure; benign functionally, confusing experientially.
• Unplaced or duplicated nav item if the returned tuple does not match an existing entry name, or if the addon also self-registers a settings page.
• Consumer-side exception if brand-context 1.16+ does not defensively validate the returned tuple.
• Entitlement ambiguity on the shared Addon-Suite page where multiple addons with differing permissions are aggregated.
• Cache staleness post-deploy, presenting as "upgrade didn't apply."

Ramp-up Near zero for engineers — the change is a single method with no migration. For support/CS and anyone maintaining admin documentation, budget a short briefing: what the method does, that it is conditional on brand-context 1.16+, that the fallback is intentional, and where settings now live in each case. This release is safe to adopt; the recommendation is to adopt it deliberately alongside a brand-context version pin rather than incidentally.