Statamic Accounts Laravel Package

Getting Started

• Install with composer require and run php please stache:clear (Statamic caches navigation and settings aggressively; a stale Stache is the most common "my change did nothing" cause).
• First place to look is the addon's service provider and its settingsNavParent() method — as of v0.5.1 this is the single declaration that decides where the addon's Control Panel settings appear. It returns a [section, name] tuple pointing at one of the addon's own CP navigation entries.
• Check your statamic-brand-context version before anything else: composer show | grep brand-context. On 1.16+ the settings render as the sub-item "Einstellungen" beneath that navigation entry; on older versions the method is silently ignored and the previous flat layout stays in place.
• First use case: open the CP, find the addon's nav entry, and confirm the settings screen is reachable as a child item rather than a top-level Settings page. If it isn't, the tuple doesn't match a real nav registration — fix that before touching anything else.
• There is nothing to migrate and no new config key in v0.5.1, so an upgrade is a composer update plus a Stache clear.

Implementation Patterns

• Declaring the parent in your own addon. Mirror the pattern: implement settingsNavParent(): array returning [section, name] where section is the CP nav section handle and name is the exact name used when you registered that nav entry. Both strings must match the navigation registration verbatim — handles are not normalised for you.
• Addons without their own navigation. Don't invent a fake nav entry just to get a parent. Leave settingsNavParent() off and the addon's settings join the shared "Addon-Suite" page under Settings, which keeps the CP sidebar from filling up with single-purpose entries.
• Version-gated behaviour. Because 1.15 and below ignore the method entirely, feature-detect rather than assume. Composer\InstalledVersions::satisfies(new VersionParser, 'vendor/statamic-brand-context', '>=1.16') is the reliable check; wrapping CP customisation in that guard keeps a single codebase working across both layouts.
• Settings access in application code. Read brand/settings values through the package's accessor rather than querying the settings store directly — the accessor is what carries defaults and fallbacks when a brand context is absent. In Antlers use the provided tag/variable; in Blade/PHP resolve through the container.
• Multi-site / multi-brand setups. Treat the active brand as request-scoped context: resolve it early (middleware or a view composer) and pass the resolved value down, instead of re-resolving inside every partial. This avoids surprising drift between the CP preview and the front end.
• Integration tip. When adding your own CP nav entry that should host settings, register the nav in the same service provider that declares settingsNavParent() so the two can't drift apart during refactors.

Gotchas and Tips

• Silent no-ops are the default failure mode. A wrong section, a wrong name, or an old brand-context version produces no error — just the old layout. When the "Einstellungen" sub-item doesn't appear, verify the tuple against the actual nav registration first, then the package version.
• Caching bites twice. Config caching (php artisan config:cache) and Stache caching both need clearing after changing navigation or settings declarations. If the CP looks right in local but wrong in staging, suspect a cached Stache, not your code.
• Ordering matters. If your nav entry is registered conditionally or in a deferred provider, settingsNavParent() may be resolved before the entry exists. Register nav unconditionally and gate the visibility instead of the existence.
• Don't hardcode the sub-item label. "Einstellungen" is supplied by brand-context, not by your addon. Asserting on that string in tests couples you to a dependency's copy; assert on the parent entry and the route instead.
• Upgrade path is clean. No migration, no new config key, no deprecations in v0.5.1 — the only behavioural change is CP layout on brand-context 1.16+. Safe to roll out; expect zero front-end impact.
• Extension point to watch. settingsNavParent() is now the supported seam for CP placement. If you've been hacking the settings screen location via nav filters or a custom CP controller, migrate to this method so future brand-context releases don't break you.