Filament Gtm Laravel Package

Getting Started

This release adds a single fluent method, so the upgrade surface is small — but it is the first knob that lets the plugin's settings page sit alongside your own resources instead of in the package's translated group.

1. Check the dependency floor first. navigationGroup() requires filament-analytics-core ^3.1. If your composer.json still pins 3.0.x, bump it before touching the panel provider:

   composer require filament-analytics-core:^3.1
   

2. Register the plugin as usual in your panel provider (app/Providers/Filament/AdminPanelProvider.php) if you haven't already:

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

3. Look at these files first: the package's Plugin class (the fluent setters and their defaults live there), the settings page class it registers, and the config/ file if one is published — that is where navigation label/sort/icon are typically read from.
4. First use case: you already have a "Reporting" or "Insights" navigation group filled with your own resources, and you want the settings page to land there rather than in the package's translated group:

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

5. Run php artisan optimize:clear and reload the panel. The page should appear under your group with no other changes; if you never call navigationGroup(), behaviour is unchanged.

Implementation Patterns

String vs Closure. Pass a plain string when the group is static. Pass a Closure when the group depends on runtime state (tenancy, feature flags, user role):

Plugin::make()->navigationGroup(
    fn () => filament()->getTenant()?->isEnterprise() ? 'Insights' : 'Analytics'
)

Share one source of truth. The most common pattern is defining group names once so resources and the plugin can't drift:

// app/Filament/Groups.php
final class Groups
{
    public const REPORTING = 'Reporting';
}

Then use Groups::REPORTING in both Resource::getNavigationGroup() and Plugin::make()->navigationGroup(...). Mismatched strings create two visually identical but separate groups.

Pair it with sort/label/icon. Grouping alone tends to dump the page at the bottom of the group; chain the other fluent setters the plugin exposes so the sidebar reads correctly:

Plugin::make()
    ->navigationGroup(Groups::REPORTING)
    ->navigationSort(10)
    ->navigationLabel('Analytics settings');

Per-panel configuration. Because the plugin is registered per panel, you can give each panel a different group — useful when an admin panel and a tenant panel expose different parts of the settings page.

Environment-aware placement. A defensible pattern for staged rollouts: put the page in the package's default (translated) group on staging, and in your own group in production, by building the plugin from a config value rather than hard-coding the string.

Integration tip: keep the plugin registration at the top of your panel() chain, before ->resources()/->pages(), so navigation ordering is deterministic when you later add your own pages to the same group.

Gotchas and Tips

• Silent no-op on old core. The method only takes effect with filament-analytics-core >= 3.1. On 3.0 you keep the translated group with no error — an easy hour lost. Verify with composer show filament-analytics-core before debugging your panel provider.
• Nothing is removed by default. This is additive: not calling navigationGroup() preserves the translated group. The upgrade is non-breaking, so the real risk is not the release but assuming a plain composer update changed your sidebar.
• Translation semantics of group names. Filament runs navigation group labels through the translator. If you pass a string that coincides with a missing translation key, you may see odd casing or an untranslated literal. When you want a literal, non-translated label, prefer the Closure form (fn () => 'My Group') or ship a matching lang entry.
• Closure cost. The closure is evaluated while building navigation — per request, per panel render. Keep it free of queries or API calls; read from already-resolved state (tenant, auth user, config).
• Whitespace and case. 'Reporting' and 'reporting' are different groups. Centralise the constant; don't retype it in three panel providers.
• Caches. Panel/navigation changes frequently appear stale because of config or route caching in local environments. php artisan optimize:clear (or config:clear + route:clear) before concluding the method is broken.
• Debugging placement. Temporarily dump() inside your closure, or inspect the panel's registered navigation groups via tinker, to confirm the group string is what you think it is.
• Multi-tenancy. Under tenancy the navigation is rebuilt per tenant; a closure that reads the tenant is the intended extension point, but make sure the closure resolves the same tenant the panel is currently rendering for.
• Extension points to watch. Because the requirement is delegated to filament-analytics-core, future navigation options (sort, icon, collapse behaviour) will likely arrive there rather than in this package — track the core changelog, not just this one, when upgrading.