Filament Hotjar Laravel Package

Getting Started

This plugin adds an analytics settings page to a Filament panel. Start here:

1. Require the package alongside its core dependency — filament-analytics-core must be 3.1 or newer for the navigation group API described below.
2. Register the plugin in your panel provider:

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

3. Load /admin (or your panel path) and open the analytics settings page. Out of the box it lands in the package's translated navigation group — no configuration required.

First use case: you already have a Filament panel with a "Settings" group and the analytics page is showing up under a separate translated heading. That's the exact problem 3.1.0 solves:

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

Implementation Patterns

Group it with your existing settings pages. The most common pattern — pin the plugin to the same group as the rest of your admin configuration:

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

Combine it with navigationSort/navigationLabel on the page if you want deterministic ordering inside the group; the group string only controls placement.

Translate the group yourself. The default group is translated by the package. If you override it with a plain string, that string is used verbatim — so pass a translated value:

Plugin::make()->navigationGroup(__('admin.nav.settings'))

Drive the group from config. Keeps panel providers clean and lets ops change placement without a deploy:

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

Use a Closure for context-dependent placement. Accepting a Closure lets you resolve the group at render time — useful for multi-panel apps where the same plugin instance is registered on more than one panel, or where the group depends on the current user's permissions/tenant:

Plugin::make()->navigationGroup(
    fn () => filament()->getCurrentPanel()->getId() === 'admin' ? 'Settings' : 'Analytics'
)

Multi-panel setups. Register the plugin per panel and give each its own group; the closure form avoids duplicating registration logic when panels share a provider trait.

Migration path. If you previously worked around the hardcoded group (custom page registration, navigationGroup on a subclassed page, or hiding the plugin page and rebuilding it), delete those workarounds and use the first-class API — otherwise you'll end up with two competing definitions.

Gotchas and Tips

• Version coupling is the big one. navigationGroup() only exists with filament-analytics-core 3.1+. If you bump this package but leave core pinned below 3.1, you'll hit a BadMethodCallException / undefined method at panel boot. Bump both in the same commit and check composer.lock in CI.
• Override replaces, it does not merge. Specifying a group drops the package's translated label entirely. There's no fallback, so a typo'd group name silently creates a new, empty-looking nav group rather than erroring.
• Closure signature. Filament navigation closures in this ecosystem are commonly invoked without arguments; don't assume the page instance is injected. If you need the page or panel, resolve it (filament()->getCurrentPanel()) rather than relying on a parameter. Verify against the source before shipping a closure that destructures arguments.
• Group ordering is a Filament concern, not this package's. Filament sorts groups by the lowest navigationSort of their children (or registration order). If your new group lands in an unexpected spot, adjust navigationSort on the analytics page or your sibling pages.
• Permissions still apply. Putting the page in Settings doesn't hide it from users who shouldn't see it — pair with canView()/->visible() or a policy as you would for any other page.
• Debugging placement: if the group doesn't change, confirm the plugin instance is the one actually registered (a second ->plugin(Plugin::make()) call elsewhere overrides expectations), and clear cached panels/config with php artisan filament:clear-cached-components and php artisan config:clear.
• Extension point to watch: navigationGroup() returns the plugin instance, so it chains cleanly with any other Plugin configuration methods — keep your plugin registration as a single fluent chain to avoid ordering surprises.