Filament Amplitude Laravel Package

Getting Started

• Install the plugin alongside its core dependency. The new navigation grouping API requires filament-analytics-core ^3.1 (or the version constraint that ships Plugin::make()->navigationGroup()); pin it explicitly in composer.json rather than letting the plugin resolve whatever is already locked, or the method simply won't behave as documented.
• Publish and run the package's migrations/config as usual, then register the plugin on the panel you actually want the analytics settings page on:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(Plugin::make());
}

• Look here first: the plugin class itself (src/Plugin.php or the package's Plugin namespace) — it is the single surface you configure. Everything day-to-day happens through Plugin::make() chained before ->plugin() hands it to the panel.
• First real use case: you already have a panel with your own navigation structure (e.g. Settings, Reporting, Administration) and the plugin's page lands in a separate translated group. Add ->navigationGroup('Settings') and it slots in with the rest of your settings pages instead of creating a one-item group.

Implementation Patterns

Static group for a single panel. The common case — consolidate the plugin page into an existing group by name:

->plugin(
    Plugin::make()->navigationGroup('Settings')
)

Match the string to the label your other resources already use. If your panel groups by translation key, pass the same key (see Gotchas).

Dynamic / per-tenant grouping with a Closure. Because the argument is string|Closure, you can resolve the group at render time — useful when tenants, roles, or panels localise their navigation differently:

Plugin::make()->navigationGroup(
    fn () => auth()->user()?->isAdmin() ? 'Administration' : 'Settings'
)

Keep the closure cheap and side-effect free; it can be evaluated during navigation building on every page render.

Multi-panel parity. Plugin registration is per panel, so call navigationGroup() on each panel that registers the plugin. Panels that omit it keep the package's translated default group — which is a perfectly valid mixed setup if only your admin panel needs consolidation.

Opting back into the default. Omitting the call is the documented way to retain the translated group. Don't pass an empty string expecting a fallback; treat "not set" and "set to a value" as the only two intentions.

Pair with your own ordering. navigationGroup() only assigns the group; where the page lands within it is governed by the panel's normal sorting conventions. Treat grouping and ordering as two separate configuration steps and set both deliberately.

Gotchas and Tips

• Version skew is the main trap. Against an older filament-analytics-core, navigationGroup() may be missing entirely (fatal BadMethodCallException) or present but ignored. After upgrading the plugin, run composer update filament-analytics-core and confirm the resolved version before debugging anything else.
• Exact-match grouping. Filament groups by label value; 'Settings' and 'settings' and 'Settings ' produce three groups. If a page spawns its own group, diff the strings before suspecting the plugin.
• Translation keys vs. literal labels. Passing a raw string bypasses the package's translated default group and your panel's own __() conventions. If your other resources use translation keys as group identifiers, pass the key — otherwise the plugin page will group separately in non-default locales.
• Closure return types. Return a string; returning null is not the documented "keep default" escape hatch — omit the call instead. Guard against unauthenticated contexts (queue jobs, artisan commands, login page) where auth()->user() is null.
• Config/opcache caching. Changes to panel configuration don't survive optimisation caches. After editing, clear with php artisan filament:optimize-clear, php artisan config:clear, and php artisan optimize:clear before concluding the setting isn't applied.
• Debugging checklist, in order: resolved core version → navigationGroup() actually called on the panel in use → string matches an existing group exactly → caches cleared. That sequence resolves nearly every report of "the page is still in the wrong group."
• Extension points. If you need conditional logic beyond a closure, subclass or decorate the plugin and re-register it from a service provider — but check Plugin.php first; the closure signature is the intended seam and is stable, whereas internal properties are not.
• Upgrade hygiene. This release is additive and non-breaking: existing registrations without navigationGroup() behave identically. There is no migration or config republish required, so keep the upgrade scoped to the dependency bump and add grouping as an explicit follow-up change.