Filament Cloudflare Web Analytics Laravel Package

Getting Started

This release adds a small but useful panel-integration point: Plugin::make()->navigationGroup(string|Closure) lets the analytics settings page live inside one of your Filament panel’s existing navigation groups. If you do not call it, the package keeps its translated default group.

Minimal setup:

1. Install/upgrade this package and ensure the companion package is on filament-analytics-core 3.1+.
2. Register the plugin in your Filament panel provider.
3. Optionally set a navigation group.
4. Clear Filament’s cached panel metadata after changing plugin registration.

use YourVendor\YourPackage\Plugin;

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

First places to look:

• The plugin class and its navigationGroup() method.
• Your panel provider’s plugin() registration.
• The panel’s existing navigation groups.
• The companion filament-analytics-core version constraint in composer.json.

First use case: add the analytics settings page to an admin panel and place it under your existing “Settings” or “Analytics” navigation group rather than leaving it in the package’s translated default group.

Implementation Patterns

Place the page in an existing settings group

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

Use this when your panel already has a settings area and you want analytics configuration to sit alongside other operational settings.

Use a closure for environment- or user-dependent grouping

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

This is useful in multi-role panels, but keep closure logic simple. Prefer panel-level registration or policy checks when the grouping depends on broader panel context.

Register different groups per panel

// AdminPanelProvider
Plugin::make()->navigationGroup('Administration')

// TenantPanelProvider
Plugin::make()->navigationGroup('Workspace settings')

Because the grouping is configured at plugin registration time, separate panels can use different navigation groups without extra config.

Keep the translated default when localization matters

If you omit navigationGroup(), the package keeps its translated group. Do not override it with a hard-coded English string unless you are prepared to translate that string yourself.

Translate custom groups explicitly

Plugin::make()
    ->navigationGroup(__('navigation.analytics'))

A custom string is just a string; it will not automatically inherit the package’s translated default.

Use it as a light integration point, not a navigation system

This method controls where the settings page appears. It does not create a navigation group, reorder other pages, or replace Filament’s normal navigation configuration. Model your broader navigation structure in the panel provider and use this method only to align the analytics page with it.

Gotchas and Tips

• Companion version mismatch is the first failure mode. This feature requires filament-analytics-core 3.1+. Upgrade both packages together and check the resolved version with composer show.
• The navigation group must already make sense in your panel. Setting navigationGroup('Reports') will not create a “Reports” group by itself; Filament will place the page under that group label, so keep naming consistent with existing pages.
• Do not pass an empty string as a workaround. If you want the default translated group, omit the call entirely rather than setting '' or null.
• Closures are convenient but easy to overuse. If the group depends on tenant, panel, or role, prefer explicit per-panel registration when possible; it is easier to reason about and debug.
• Clear caches after changing registration. Filament can cache panel and navigation metadata. Run php artisan filament:optimize-clear and, if needed, php artisan optimize:clear.
• Check plugin registration before debugging the navigation method. If the page is missing or still in the old group, confirm the plugin is registered on the correct panel provider and that you are not editing a cached deployment artifact.
• Translation behavior changes when you customize the group. The default group is translated by the package; a custom group is your responsibility. Use __() if your application has multiple locales.
• Extension point: navigationGroup() accepts a Closure, so dynamic grouping is supported, but keep the closure deterministic for a given user/panel to avoid confusing navigation behavior between requests.
• Upgrade note: this is an additive release. Existing installations that do not call navigationGroup() should keep the translated default group, so no migration is expected for normal usage.