Statamic Affiliates Laravel Package

Getting Started

This addon is a Statamic Control Panel addon whose visible surface area is its settings screen. The v0.2.1 release only changes where that screen appears in the CP, so a new developer's first hour is mostly orientation.

1. composer require the addon, then php artisan config:clear && php artisan view:clear (Statamic will discover the addon via its service provider; no migration or new config key exists as of v0.2.1, so there is nothing to publish just to get running).
2. Look first at the addon's service provider (nav registration), then src/ for the settings class and resources/views/ for the CP screen. The nav entry is the anchor for everything else.
3. First use case: open the CP, find the addon's own navigation entry, and open its Einstellungen sub-item. On statamic-brand-context < 1.16 you will instead find the screen under Settings → Addon-Suite; both are valid, and knowing which one you're looking at saves a confusing first debug session.

Prerequisite worth pinning in your README: statamic-brand-context ^1.16 to get the nested layout. The addon still works below that — the method is simply ignored.

Implementation Patterns

Read settings through the addon's settings class, never by scraping the CP screen. The nav relocation in v0.2.1 is purely presentational; values and keys are unchanged, so any code reading settings keeps working across the upgrade.

If you are building a sibling addon, implement settingsNavParent(): array yourself. It returns a [section, name] tuple pointing at your own CP navigation entry. That is the sanctioned way to get your settings rendered as a sub-item of your nav rather than dumped into the shared Addon-Suite page. Keep the tuple in a constant or a single method so the nav registration and the settings declaration can't drift apart.

Never hardcode the settings URL. The path differs between brand-context versions (nested under your nav vs. under Settings → Addon-Suite) and will differ again if the suite page is renamed. Generate links with cp_route(...) / the named route, and if you must link from a Blade view, resolve it at render time.

Branch on capability, not on a version string, where you can. If your own code needs to behave differently depending on where settings live, prefer a method_exists()-style check or Composer\InstalledVersions::satisfies() over parsing statamic-brand-context versions by hand. The addon itself already degrades gracefully, so mirror that politeness.

Test both layouts. A feature test that asserts the settings screen is reachable should assert on route name / response, not on a literal path fragment like /cp/settings/addon-suite/..., or it will break for half your matrix.

Upgrade workflow: bump the brand-context constraint, run the test suite, then click through the CP once. There is no migration step, so a failed upgrade is almost always a stale cache or a nav-tuple mismatch rather than data.

Gotchas and Tips

• The fallback is silent. If settingsNavParent() returns a section/name that doesn't match a registered nav entry (typo, renamed nav, addon nav disabled by permission), you don't get an error — you get the shared Addon-Suite page. Treat "settings ended up in the wrong place" as a nav-registration bug, not a settings bug.
• The method is ignored, not emulated, on older brand-context. On < 1.16 there is no error and no deprecation notice; the old layout simply persists. Don't write code that assumes the sub-item exists on every install.
• Version-gated URLs break bookmarks and docs. Anyone who saved a direct link to the settings screen — support articles, onboarding docs, Slack pins — will land on a 404 or the wrong page after upgrading brand-context. Regenerate links rather than storing them.
• Cache first, always. After upgrading: php artisan config:clear && php artisan view:clear. With no migration and no new config key, a "broken" upgrade is nearly always cached nav/config.
• Label collisions in the suite. Multiple addons without their own nav share one Addon-Suite page; if two of them use the same settings label, the page shows duplicates with no disambiguation. Give your settings a distinct name, and if you're shipping a suite, give each addon its own nav entry so each can own its settingsNavParent().
• The visible label is localised ("Einstellungen"). Don't rename it in your own overrides expecting it to propagate — and don't assert on the English string in tests.
• settingsNavParent() is the extension point. It exists precisely so you don't monkey-patch nav registration or reach into brand-context internals. If you find yourself filtering nav items in a listener to reposition settings, you're working against the design.
• Debugging order: (1) is brand-context ≥ 1.16? (2) does the tuple match a nav that is actually registered and visible to the current user's permissions? (3) are caches cleared? Those three cover essentially every reported layout issue in this release.