Analytics Core Filament Laravel Package

Getting Started

Know what you're installing. This is a presentation adapter — it wires the analytics-core domain package into Filament panels (pages, widgets, resources). It almost certainly does not contain the metrics/aggregation logic itself. Plan on pulling in the core package and its data source before anything renders meaningfully. Verify by reading composer.json in the repo: whatever the adapter requires is your real dependency list.

Minimal setup:

composer require liberusoftware/analytics-core-filament

Then register the plugin in your panel provider:

// app/Providers/Filament/AdminPanelProvider.php
use Liberusoftware\AnalyticsCoreFilament\AnalyticsCoreFilamentPlugin;

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

If the package ships config or migrations, publish them before first boot:

php artisan vendor:publish --tag="analytics-core-filament-config"
php artisan vendor:publish --tag="analytics-core-filament-migrations"
php artisan migrate
php artisan filament:assets

Where to look first, in this order:

1. src/*Plugin.php — the Plugin contract implementation. This tells you every widget, page, and navigation item the adapter registers, and which methods are chainable for configuration.
2. composer.json — Filament major version constraint and the core package constraint. Match these against your app before installing.
3. config/analytics-core-filament.php (if present) — the actual knobs. Most "how do I change X" questions are answered here.
4. resources/views/ — the widget blades. This is where you'll override presentation.
5. src/Widgets/ — the Livewire widget classes; these are your extension points.

First use case: get one widget on screen with real data. Log into /admin, confirm the plugin's navigation group appears, open the analytics page, and check that a date-range filter actually mutates the numbers. If the widget renders but stays empty, the problem is upstream (core package / data source), not the adapter — that distinction saves hours.

Implementation Patterns

Register per panel, not globally. Filament plugins are panel-scoped. If you have an AdminPanelProvider and a TenantPanelProvider, register deliberately — the adapter's widgets are usually the kind of thing you want exposed to staff but not to customers.

->plugin(
    AnalyticsCoreFilamentPlugin::make()
        ->navigationGroup('Insights')
        ->navigationSort(10)
)

Confirm the actual fluent methods exist in the plugin class before relying on them; adapters this thin often only expose two or three.

Treat widgets as the composition surface. The standard day-to-day workflow is: enable the shipped widgets on your dashboard, then write your own widgets that pull from the core analytics service.

// app/Filament/Widgets/SignupsThisWeek.php
class SignupsThisWeek extends ChartWidget
{
    protected static ?string $heading = 'Signups (7d)';

    protected function getData(): array
    {
        $series = app(AnalyticsService::class)
            ->query('signups', now()->subDays(7), now());

        return [
            'datasets' => [['data' => $series->pluck('value')->all()]],
            'labels'   => $series->pluck('label')->all(),
        ];
    }
}

This is the highest-leverage pattern: the adapter gives you the chrome (filters, layout, navigation), you supply the query. It also keeps you out of the adapter's internals when it changes.

Override views rather than editing vendor code. Filament's view resolution means you can shadow a widget blade in resources/views/vendor/analytics-core-filament/... after publishing, or point a widget at your own blade with ->view('filament.widgets.my-analytics'). Do this for branding and layout — never fork the repository for cosmetic changes.

Scope to tenancy explicitly. If you use Filament's tenancy, widgets need to respect Filament::getTenant(). Aggregates that cross tenants are a data-leak class of bug, and presentation adapters frequently don't guard this for you. Add a canView() or getData() guard on every widget you expose in a tenant panel:

public static function canView(): bool
{
    return auth()->user()?->can('viewAnalytics', Filament::getTenant()) ?? false;
}

Wire up authorization at the policy layer. Analytics is sensitive. Use Filament's canViewAny on pages and canView on widgets rather than hiding links in navigation — hidden navigation is not access control.

Compose with the core package, don't duplicate it. If you find yourself writing SQL inside a widget, ask whether the metric belongs in analytics-core instead. Keeps the adapter thin and keeps your reporting logic testable without booting Filament.

Test with Livewire, not HTTP. Livewire::test(MyAnalyticsWidget::class)->assertSee(...) catches most regressions and runs fast. Add one smoke test that mounts the panel's analytics page — this catches version-drift breakage immediately after a Filament upgrade.

Gotchas and Tips

Filament major-version drift is the number-one risk. This adapter sits directly on Filament's internal APIs (Widget, Page, Plugin, Dashboard), which change between v3 and v4. Before installing, check the composer.json constraint and pin it. If you're on Filament v4 and the adapter targets v3, you will get silent breakage in widget registration rather than a clean error. Read the release history; a single release dated in the future and zero dependents is a strong signal nobody has exercised the v4 path yet.

License is NOASSERTION. This is not a permissive-license declaration — it means the package metadata doesn't parse to a recognized license. Before this goes anywhere near production or a client deliverable, get the LICENSE file from the repo and have someone read it. If it's absent entirely, treat it as all-rights-reserved.

Zero stars, zero dependents means you are the QA department. Pin the exact version in composer.json (no ^), vendor-fork it into your own namespace if you need patches, and write a smoke test around it. Don't assume the upgrade path is smooth, and don't file a bug expecting a fast turnaround.

Empty widgets are usually a data-source problem. The adapter renders; the core package supplies. When a chart is blank, check in this order: (1) is there data in the underlying store for the selected range, (2) is the core package's migration/seeding done, (3) is caching returning a stale empty result. Add a php artisan analytics:clear-cache-style step to your deploy script if the core package offers one — otherwise inspect the config's cache TTL and flush the relevant store manually.

Timezone and range boundaries. Date filters built on now() in the app timezone versus stored UTC timestamps is the classic off-by-a-day reporting bug. Set a single timezone in config/app.php, make sure the widget's range picker resolves against the same zone, and test at month boundaries specifically.

Performance hides in the widget layer. Each dashboard widget is a separate Livewire request. Six widgets firing six unindexed aggregate queries will make the page crawl. Aggregate at the query level (SUM/GROUP BY) rather than ->get()->sum(), add indexes on whatever timestamp column the date filter hits, and consider caching per-widget with an explicit TTL.

Asset publishing is easy to forget on deploy. php artisan filament:assets needs to run anywhere views/styles are compiled. Missing it produces an unstyled dashboard that looks like a broken install. Pair with php artisan filament:optimize on production and filament:optimize-clear locally when things look stale.

Extension points, ranked by stability: config file → published views → ->view() on your own widget subclasses → the plugin's fluent setters → the plugin's src/ classes directly. Anything at the last level will break on a vendor update; keep a note of what you touched so an upgrade review is a five-minute diff.

Debugging registered widgets: dump the panel object in a tinker session (Filament::getPanel('admin')->getWidgets()) to confirm what the plugin actually added. Filament fails quietly when a widget class doesn't autoload, and this is the fastest way to see whether the problem is registration or rendering.