Filament Umami Laravel Package

Getting Started

Requires filament-analytics-core 3.1+ if you intend to use the new navigationGroup() API. Start by bumping the core dependency, then update the plugin registration in your panel provider:

use Vendor\Analytics\AnalyticsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            AnalyticsPlugin::make()
                ->navigationGroup('Settings'),
        ]);
}

The first practical use case is simply moving the analytics settings page out of its translated default group and into a group your panel already uses (e.g. Settings, Configuration, Reporting). If you do nothing, behavior is unchanged: the package keeps its translated navigation group, so this release is non-breaking.

Where to look first:

• The Plugin class (make() / navigationGroup()), which is the fluent entry point.
• The service provider that registers the settings page and its navigation metadata.
• filament-analytics-core 3.1 release notes, since the grouping behavior is implemented there.

Implementation Patterns

Static grouping for a single panel

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

Use this when the plugin lives alongside other reporting pages and you want a coherent sidebar section.

Closure-based grouping for dynamic labels

Because the parameter is string|Closure, you can resolve the group at render time — useful for localization or role-based layouts:

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

Keep closures pure and cheap: they are evaluated during navigation building, so avoid queries, container resolution of heavy services, or per-request HTTP calls.

Aligning with existing Filament groups

Match the exact string used by other plugins/pages in the panel. Filament groups by label, so 'Settings' and 'settings' will render as two separate sections. Centralize the group name in a config constant or enum-backed helper if several plugins need to share it.

Multi-panel setups

Register the plugin per panel and set the group individually. A common pattern is a shared admin panel using 'Settings' and a lighter client panel using 'Account', or omitting navigationGroup() entirely so the translated default applies.

Pairing with navigation sort/icon

navigationGroup() only affects grouping; ordering within the group still comes from the page's navigation sort. When moving the page into a crowded group, set an explicit sort so it doesn't land unpredictably relative to other plugin pages.

Gotchas and Tips

• Version constraint matters. navigationGroup() depends on filament-analytics-core 3.1. Composer will not stop you from calling the method if you pin an older core, so verify composer show / composer why after upgrading. A missing method surfaces as a BadMethodCallException at panel boot.
• No behavior change by default. Omitting the call preserves the translated group. Do not "fix" the group name in a release upgrade unless you want the sidebar to move.
• Exact string matching. Filament groups by label equality. Trailing spaces, casing differences, or a translated string vs. a literal will silently create duplicate groups rather than throwing.
• Closures are not cached by the plugin. If you use a closure for localization, ensure the panel rebuilds navigation on locale change (Filament generally does, but custom caching layers can interfere). Avoid now(), random values, or request-dependent output in the closure unless that instability is intentional.
• Permissions are unrelated. Moving the page into a group does not change authorization. Keep using the plugin's/page's existing canAccess/policy configuration; grouping is presentation only.
• Debugging. If the page disappears or appears in an unexpected group, inspect the resolved navigation via php artisan filament:optimize-clear (or clearing cached components) and dump the registered pages through Filament's panel inspection helpers. Stale caches after a plugin upgrade are a frequent cause of "my new group isn't applied".
• Extension point. This is a fluent setter on the plugin instance; if you maintain a wrapper or preset plugin factory, forward the argument rather than reimplementing navigation logic, so future core changes to grouping continue to apply.
• Upgrade hygiene. Since 3.5.0 is additive, rollout can be incremental: upgrade the package, confirm the default translated group still renders, then opt into navigationGroup() panel by panel.