Filament Pan Analytics Widget Laravel Package

Getting Started

This is a Filament panel plugin for surfacing Pan Analytics data as a dashboard widget. The 5.0 release is a platform jump: it targets Filament 4 and 5, Laravel 12 and 13, and PHP 8.3–8.5. If you are still on Filament 3, stay on the 4.x branch.

Minimal setup:

1. Require the 5.x release with Composer.
2. Register FilamentPanAnalyticsWidgetPlugin in each Filament panel where the widget should appear.
3. Configure authorization if the widget should not be visible to every panel user.
4. Open the dashboard and confirm the widget renders. If there is no data, the new empty state explains where the data comes from.

use YourPackageNamespace\FilamentPanAnalyticsWidgetPlugin;

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

First use case: add the widget to an admin or operations dashboard for users who already have access to Pan Analytics. Restrict it immediately with ->authorize(...):

FilamentPanAnalyticsWidgetPlugin::make()
    ->authorize(fn () => auth()->user()?->can('viewPanAnalytics') ?? false);

Where to look first:

• The plugin class for authorize(), isSearchable(), and current().
• The widget class for the table columns and empty-state behavior.
• Translation files for not_available, empty.heading, and empty.description.
• The 4.1.0 changelog as well as 5.0.0, since 5.0 includes all 4.1.0 fixes.

There is no install command in 5.0. Registration is manual through the panel plugin API.

Implementation Patterns

Register per panel, guard with current(). The plugin is panel-scoped. In multi-panel applications, register it only where needed. When shared code needs to know whether the plugin is active, use FilamentPanAnalyticsWidgetPlugin::current(), which returns null on a panel without the plugin.

$plugin = FilamentPanAnalyticsWidgetPlugin::current();

if ($plugin !== null) {
    // safe to interact with plugin state
}

Authorization as a first-class configuration point. Use ->authorize(bool|Closure) to keep the widget out of the dashboard for unauthorized users. Prefer a policy or permission check over a role-name check. If the closure can run for guests, return false explicitly.

FilamentPanAnalyticsWidgetPlugin::make()
    ->authorize(fn (): bool => auth()->user()?->can('viewAny', AnalyticsReport::class) ?? false);

Searchable configuration renamed. Replace any getSearchable() call with isSearchable(). This is a hard rename, not an alias, so search the codebase and any custom panel configuration before upgrading.

FilamentPanAnalyticsWidgetPlugin::make()
    ->isSearchable();

Pagination is now fixed. Page size options are 5, 10, 25, and 50. The previous “all” option is gone. If your team relies on “all” for exporting or scanning, plan a replacement workflow rather than expecting the widget to expose it.

Empty states are intentional. The widget now has an empty state explaining where data comes from. Treat that state as “no data or no source configured,” not as a rendering failure. Check Pan Analytics connectivity and data availability before debugging Filament.

No JavaScript build step. The package ships no assets and no JS tooling. Do not add package-specific asset build steps to CI. If you customize presentation, do it through Filament and the package’s supported extension points rather than expecting published frontend assets.

Strict types and static analysis are part of the package contract. The source and tests use strict types, Larastan 3 at max level, and architecture tests. If you extend package classes or override behavior, add declare(strict_types=1);, type your properties and return values, and run PHPStan/Larastan in your own application.

Testing without the removed mixin. The testing mixin is gone. Use Filament and Livewire test helpers directly. For a dashboard test, assert the widget is present or absent based on authorization, and assert the empty-state translation keys when there is no data.

livewire(Dashboard::class)
    ->assertSee(__('filament-pan-analytics-widget::widget.empty.heading'));

Adjust the translation namespace to match the package’s actual namespace.

Translation overrides. The headers.id key was removed, and not_available, empty.heading, and empty.description were added. If you publish or override translations, update those keys rather than carrying forward the old header key.

Gotchas and Tips

• Filament 3 is not supported by 5.x. Keep Filament 3 applications on the 4.x branch. Do not widen the package constraint and the Filament constraint independently without testing the full matrix.
• getSearchable() will fail after upgrade. Rename it to isSearchable() everywhere, including custom panel providers and tests.
• The “all” page size is gone. Update acceptance tests, screenshots, and user documentation that mention showing all rows. Supported sizes are 5, 10, 25, and 50.
• Removed install command. Do not document or script an install artisan command for 5.x. Register the plugin manually.
• Removed facade and widget class. Remove references to the old facade and the removed FilamentPanAnalyticsWidget class. Use the plugin API and the widget supplied by the package.
• Removed view namespace. Do not rely on publishing or overriding package views. Use translations and the plugin’s supported configuration points instead.
• No assets means no asset publish step. If deployment scripts run package asset publishing or npm builds for this package, remove those steps.
• current() can return null. Always null-check it before calling plugin methods. This is especially important in shared dashboard code used by multiple panels.
• Authorization closures should fail closed. Return false for guests or missing users. Avoid throwing inside authorize() unless you want the panel to surface an error rather than hide the widget.
• Empty state is not an error state. If the widget shows the empty message, verify Pan Analytics credentials, data source configuration, and whether the selected period actually contains data.
• Translation key changes can break overrides. Search for headers.id in your lang files and replace it with the new keys where appropriate.
• Number columns are right-aligned. This is cosmetic, but snapshot tests or visual regression tests may need updates.
• Strict types can expose extension code. If you subclass or decorate package classes, ensure your signatures are compatible and run Larastan at a high level.
• Debugging panel registration: call FilamentPanAnalyticsWidgetPlugin::current() in a panel-aware context. If it is null, the plugin is not registered on that panel.
• Multi-panel applications: register the plugin in every panel that needs it. A plugin registered on one panel will not appear on another, and current() will reflect that.
• Included 4.1.0 fixes: review the 4.1.0 release notes for behavior changes that may affect production even if you are jumping straight to 5.0.