Filament Matomo Laravel Package

Getting Started

The plugin (filament-analytics integration) exposes a Filament Plugin object you register on a panel. Minimal setup:

1. composer require the package (and ensure filament-analytics-core is at ^3.1 — the new navigationGroup() only takes effect with that core version).
2. Publish/verify any config or migrations the package ships with (php artisan vendor:publish, php artisan migrate).
3. Register the plugin in your PanelProvider:

->plugin(Plugin::make())

Without further config, the settings page lands in the package's translated default navigation group. First use case: if your panel already has a custom group (e.g. “Analytics”, “Reporting”, “Settings”), call navigationGroup() to place the page there instead of creating an orphan group.

Implementation Patterns

• Static group assignment — the common path:

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

  The string must exactly match the label of an existing group (including translation key output) to merge into it.
• Closure for dynamic grouping — useful for localization, role-based grouping, or reading config at boot:

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

• Per-panel configuration — because the group is configured on the plugin instance, register a differently-configured plugin on each PanelProvider. This is the clean way to show the settings page in different groups per panel (admin vs. tenant).
• Combining with other plugin builders — chain navigationGroup() with navigationLabel(), navigationIcon(), navigationSort() etc. in the same fluent call so ordering and grouping are co-located.
• Fallback behaviour — if you omit navigationGroup(), the translated default group is retained, which keeps existing installs rendering unchanged after upgrading to 3.4.0.

Gotchas and Tips

• Core version gate — navigationGroup() requires filament-analytics-core >= 3.1. On older core the method may exist but the group is ignored and you silently keep the translated default. Pin the core in composer.json if grouping is critical.
• Exact-match merging — Filament merges navigation items by group label. A typo, trailing space, or untranslated string will create a second, visually near-identical group rather than joining the intended one. Match the label exactly as it appears in getNavigationGroups().
• Closure return contract — the signature is string|Closure; make sure your closure resolves to a string at render time. Returning null (e.g. from a missing translated key or a null user in a queue/console context) is undefined behaviour for the group resolution — guard with ?-> and a sensible default.
• Cache clearing — panel component caching and config caching can make a changed group label appear stale. After editing the provider, run php artisan optimize:clear (or filament:optimize-clear where available) before debugging “the group didn’t change”.
• Upgrade safety — 3.4.0 is additive: no deprecations, no breaking changes. Safe to bump in place; existing panels keep the translated default unless you opt in.
• Extension point — the string-or-closure signature is the intended hook for multi-tenant or role-aware navigation. Prefer it over overriding the page’s getNavigationGroup() in a subclass, which fights the plugin config and is harder to test.
• Debugging — if the item appears in the wrong place, inspect the registered groups on the panel (Filament::getCurrentPanel()->getNavigationGroups()) to confirm the exact label your plugin is trying to merge into.