Filament Clarity Laravel Package

Getting Started

filament-analytics-core 3.1 adds one small but high-leverage knob to the plugin: navigationGroup(). It controls which navigation group the analytics settings page is filed under in your panel.

Minimal setup:

composer require filament-analytics-core:^3.1

Then register the plugin in your panel provider, before or alongside your other plugins:

use Filament\Panel;
use Filament\PanelProvider;
use Vendor\Analytics\AnalyticsPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->plugin(
                AnalyticsPlugin::make()
                    ->navigationGroup('Settings'),
            );
    }
}

Look first at the panel provider where the plugin is already registered — that is the only place navigationGroup() matters. The first use case is almost always "our admin panel has a Settings group and the analytics page is landing in a generic, translated group that doesn't match our information architecture." Add the call, clear the config cache, and the page moves.

If you are not yet on core 3.1, the method does not exist and you will get a BadMethodCallException from the plugin's macro/proxy layer — upgrade core first.

Implementation Patterns

Static group for a fixed IA. The common case. Match the string exactly to the group label your other resources use:

AnalyticsPlugin::make()->navigationGroup('Insights')

This is a cosmetic change only — it does not affect routing, authorization, or the settings page URL, so links and bookmarks keep working.

Closure for localized or tenant-dependent groups. Because the signature accepts string|Closure, you can defer resolution to render time:

AnalyticsPlugin::make()
    ->navigationGroup(fn () => __('navigation.groups.analytics'))

Useful when a panel is shared across locales, or when the group name is derived from configuration that is not available at provider boot. The closure is resolved when the navigation is built, so per-request values (current team, locale) are safe.

Pair with navigationSort() for deterministic ordering. Grouping and ordering are separate concerns; if the analytics item lands first or last within the new group, set a sort that leaves room for neighbours:

AnalyticsPlugin::make()
    ->navigationGroup('Settings')
    ->navigationSort(10)

Multi-panel setups. The method is per-plugin-instance, so each panel can group analytics differently. Register the plugin separately in each panel provider rather than sharing a single configured instance — plugin instances carry mutable state.

Incremental migration. Adopt navigationGroup() panel by panel. Leave low-traffic panels on the default translated group and only override where users actually complain about discoverability. This keeps the diff reviewable and avoids a big-bang navigation reshuffle.

Gotchas and Tips

• Hard dependency on core 3.1. The method is a thin forward to filament-analytics-core. If you constrain core below 3.1 in composer.json while allowing the plugin to float, Composer may resolve a combination where the call fails at runtime rather than install time. Pin both.
• Default behaviour is preserved, not deprecated. Omitting the call keeps the translated group. That is intentional and stable — do not treat the absence of the call as technical debt.
• Return value is the plugin, not the group. It is fluent, so chain order does not matter, but do not try to read the group back off the plugin to drive your own navigation logic; resolve that from your own config.
• Closures run on navigation build. Anything expensive inside the closure (queries, HTTP) runs on every page render that builds navigation. Return a computed string from config or cache instead.
• Cache clear after changing groups. Navigation is not cached by Filament itself, but panel/plugin configuration is often cached by your own config cache or by filament:optimize. Run php artisan filament:optimize-clear (or optimize:clear) after edits, then hard-refresh — stale nav is the most common "the method didn't work" report.
• Group label is the key, not the slug. Filament matches groups by their rendered label. If your Settings group is localized elsewhere and you pass a raw English string here, you silently create a second, near-identical group. Use the same resolution strategy (literal or __()) in both places.
• Authorization is untouched. Users who could not see the page before still cannot see it. If the page is invisible after the change, check policies and canViewAny-style gates before blaming navigation.
• Empty groups can render. Moving an item out of the default group can leave an orphaned group header if nothing else lives there; audit the nav after the first change.
• Extension point. Because the closure is evaluated lazily, this is the natural place to hook environment- or tenant-specific grouping without subclassing the plugin — prefer it over overriding the plugin's navigation registration.