Filament Metrics Plausible Laravel Package

Getting Started

This release adds Plugin::make()->navigationGroup(...) to the Filament plugin, letting the analytics settings page sit in one of your panel's own navigation groups instead of the package's translated default (requires filament-analytics-core 3.1).

1. Require the package and its core dependency (filament-analytics-core ^3.1) and run migrations if prompted.
2. Register the plugin on your panel in app/Providers/Filament/*PanelProvider.php:

use Vendor\Analytics\Plugin;

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

3. Clear caches (php artisan filament:optimize-clear or optimize:clear) and reload the panel — the settings page should now appear under Insights.

First use case: drop the analytics settings page next to your other admin/settings resources so operators find analytics configuration where they already look, rather than in a separate translated group.

Implementation Patterns

Static group name — the common case, matching an existing NavigationGroup or plain string used elsewhere in the panel:

Plugin::make()->navigationGroup('Reports')

Closure for context-dependent grouping — evaluate per-request or per-user; useful when group naming depends on tenant, locale, or permissions:

Plugin::make()->navigationGroup(fn () => auth()->user()?->isAdmin()
    ? 'System'
    : 'Analytics')

Conditional registration — only set the group when your panel actually defines it, otherwise leave the package default intact:

$plugin = Plugin::make();

if ($panel->getNavigationGroups()->isNotEmpty()) {
    $plugin->navigationGroup('Insights');
}

Panel provider extraction — for multi-panel apps, keep plugin configuration in a small helper or config-driven factory so each panel's group naming stays consistent:

Plugin::make()->navigationGroup(config('analytics.navigation_group'))

Integration tips

• Prefer reusing a group string already present on the panel so Filament collapses them into one sidebar section rather than creating a near-duplicate.
• Combine with ->navigationLabel() / icon methods (if exposed by the plugin) to fully control the settings entry.
• If your panel uses clustered navigation, verify the group is registered at the panel level; an unregistered group name still renders but may sort unexpectedly.
• For tenant-aware panels, resolve the closure against the current tenant rather than at boot, since Filament builds navigation per request.

Gotchas and Tips

• Core version coupling. navigationGroup() requires filament-analytics-core 3.1+. On older core the method may be absent or silently ignored — check composer show before debugging navigation.
• Unregistered groups. Passing a group name your panel doesn't declare works, but ordering and collapse state are Filament's defaults, not yours. Register the group on the panel if position matters.
• Closures run often. Filament evaluates navigation on each render; keep closures cheap and side-effect free (avoid queries beyond what you already do for auth).
• Caching. After changing the plugin config, run php artisan filament:optimize-clear if you use filament:optimize; cached component/navigation data will otherwise show the old group.
• Falling back to the default. Passing null (or not calling the method) preserves the package's translated group. If you want translated behavior back, remove the call rather than passing an empty string — '' is a group name, not "unset".
• Localization interactions. The translated default respects the app locale; once you override with a string, that string is not translated. If you need localization, return __('navigation.groups.insights') from a closure.
• Debugging. If the page lands in the wrong place, dump the resolved group via the plugin getter (or dd() inside your closure) and compare against $panel->getNavigationGroups(); ordering is decided by the panel's group registration first, then plugin insertion order.