Statamic Funnels Laravel Package

Getting Started

• Install alongside statamic-brand-context and goldnead/statamic-flow-canvas. Two constraints now matter: brand-context >=1.16 (the version that starts honouring settingsNavParent()) and flow-canvas ^1.6.1 (the version whose shared canvas components carry their own plain CSS). Run composer require and check composer show for both constraints.
• If you are already on brand-context >=1.16 and flow-canvas >=1.6.1, this release is a drop-in: no migration, no new config key, nothing to publish. The only shipped artefact is a rebuilt Control Panel bundle.
• Look first at the addon's settingsNavParent() implementation — it returns a two-element array [section, name] identifying the addon's own Control Panel navigation entry. That pair is the contract the brand-context integration introduces, so read it before anything else.
• Then check your CP: with brand-context >=1.16 the addon's settings screen should render as the sub-item "Einstellungen" beneath your addon's nav entry, rather than as a separate top-level settings page. With flow-canvas ^1.6.1 the canvas control bar, node actions, section headers and adder icon should look correct even on an install where this addon is the only one present.
• First real use case: you maintain or install several Statamic addons that all expose settings. Addons that declare a nav parent get their settings nested under their own entry; addons that do not are collected onto a single shared "Addon-Suite" page under Settings. That consolidation is the day-to-day win — fewer top-level Settings children, and settings discoverable from the addon's own nav section. The flow-canvas bump is the complementary win for the canvas UI itself: styling no longer depends on a neighbour being installed.

Implementation Patterns

• Declare the parent explicitly. Implement settingsNavParent(): array returning the same [section, name] your nav registration uses. Treat it as a mirror of your nav definition, not an independent value — the two must stay in sync.
• Prefer the suite fallback over duplicating nav. If your addon has no CP navigation of its own, do not invent one just to get a dedicated settings page. Leave settingsNavParent() out (or return nothing meaningful) and let the addon land on the shared "Addon-Suite" page under Settings. This keeps the CP tidy and is the intended path for small utilities.
• Version-tolerant integration. Older brand-context releases ignore the method and keep the previous layout. If you support both, write your own tests/assertions against layout rather than assuming nesting — e.g. assert the settings route/screen works regardless of where the nav places it, and keep any nav-related expectations in a version-gated test.
• Read settings through the addon's normal accessor (blueprint-backed config/Settings repo) rather than reaching into nav metadata. settingsNavParent() is purely a navigation hint; it carries no data about the settings themselves.
• Treat flow-canvas as a real dependency, not an incidental one. Since the canvas components ship their own plain CSS from 1.6.1, your package should declare goldnead/statamic-flow-canvas: ^1.6.1 (or whatever your addon actually requires) rather than assuming a host site happens to install it. If you build your own canvas UI on top of these components, stop supplying the divider/header/icon utilities yourself — they are now redundant and can drift from upstream.
• CI matrix. If your package or site ships a composer constraint spanning brand-context <1.16 and >=1.16, run the test suite against both. Behaviour diverges only in nav placement, so a nav-focused smoke test plus the existing settings tests is usually enough. Add a low/high flow-canvas axis if you still test against 1.6.0 — that run is the one where visual regressions are expected and should be treated as known.
• Integration tip for suites: when several addons in one install declare the same [section, name], they group under that entry. Coordinate the pair across packages (a shared constant or documented literal) instead of hard-coding it in each repo.
• Visual verification after upgrade: load the canvas in the CP and confirm the control bar divider, node actions, section headers and adder icon render. That is the complete blast radius of this release.

Gotchas and Tips

• Silent no-op on old brand-context. There is no error, deprecation notice, or warning if the installed brand-context predates 1.16 — the method is simply ignored and the old layout remains. If a user reports "settings still in the wrong place", check the brand-context version first, not the addon.
• Silent visual no-op on old flow-canvas. 1.6.1 is a hard composer constraint, so a stale install should fail composer update rather than render badly — but a site with a pinned 1.6.0 in its lockfile, or one that has not rebuilt CP assets, will still show the old unstyled-dividers look. If canvas chrome looks broken after the upgrade, check composer show goldnead/statamic-flow-canvas before filing a styling bug.
• Mismatched [section, name] is the likely failure mode. The pair must match the registered navigation entry. A typo or a nav renamed without updating settingsNavParent() will not necessarily throw; it can leave the settings item orphaned or falling back to the shared page. Keep the nav registration and the method adjacent in the codebase so they are edited together.
• No migration, no new config key, nothing to publish. Upgrading is safe and reversible. But this release does rebuild the CP bundle — so if the canvas styling or nav layout does not change after composer update, clear compiled CP assets/opcode cache before suspecting the upgrade. There is nothing to vendor:publish and no cache key that needs clearing beyond the standard asset pipeline.
• Don't overload settingsNavParent(). It declares navigation parentage only. Do not try to smuggle permissions, ordering, or icons through it; those belong to the nav registration itself.
• Debugging order: verify what the addon returns (dump the array), verify the nav section/name actually registered in the CP, then verify the brand-context version. For visual complaints, substitute flow-canvas version and CP asset cache for the last two steps. Those sequences resolve nearly every layout complaint quickly.
• Extension point to watch: the shared "Addon-Suite" page is the designated home for addons without nav. If you later add a CP nav to an addon, remember to add settingsNavParent() in the same change — otherwise it silently stays on the suite page while gaining a nav entry that has no settings sub-item.
• If you were relying on borrowed Tailwind utilities. Anyone who previously patched the canvas look by defining the divider/header/icon classes globally in their own CP CSS may now get duplicated or conflicting rules. Delete the workaround; upstream owns those styles from 1.6.1 onwards.
• Upgrade note for site owners: the settingsNavParent() behaviour is presentation-only — no data shape, routes, or config changed, so it is safe to roll out independently of application deploys. The flow-canvas bump is also presentation-only, but it is a composer constraint change, so it must be deployed with the code rather than separately.