Laravel Analytics Nova Tool Laravel Package

Getting Started

This package wraps sergeybruhin/laravel-analytics and exposes its Visitor / Session data as Filament resources. You are effectively installing two packages, and the relationship between their versions matters more than usual for a 0.x dependency.

composer require <vendor>/<this-package>
php artisan vendor:publish --tag="<this-package>-migrations"   # if applicable
php artisan vendor:publish --tag="<this-package>-config"
php artisan migrate

Check what actually got installed before you write any code:

composer show sergeybruhin/laravel-analytics
composer why sergeybruhin/laravel-analytics

You want 0.0.2 or higher. On 0.0.1 the Visitor::sessions() and Session → pageViews/events relations are missing, and every resource in this package that eager-loads them will blow up with BadMethodCallException: Call to undefined method ...::sessions().

Where to look first: the package's service provider (to see which resources/widgets it auto-registers) and its config file. Then open one resource class and trace its table() / getEloquentQuery() — that query is the contract between this package and the analytics models, and it's where nearly all customisation happens.

First use case: register the plugin on a panel and open the visitors table. That one screen exercises the whole stack — migrations, the Visitor model, the Session HasMany, and the resource query — so if it renders, your install is sound.

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

Implementation Patterns

Register per-panel, not globally. The resources are ordinary Filament resources; registering them on a specific panel lets you keep analytics out of customer-facing panels and avoid leaking visitor data across tenant boundaries.

Use the relations, don't re-query. The whole point of the 0.0.2 relations is that you can build custom widgets on top of them cheaply:

Visitor::query()
    ->withCount('sessions')
    ->where('created_at', '>=', now()->subDays(30))
    ->orderByDesc('sessions_count')
    ->limit(10)
    ->get();

This is where you should invest your time. The shipped resources cover the common views; the widgets you write against Visitor/Session are what make the package fit your product.

Extend before you fork. Subclass the resource classes and swap them in the plugin's configuration. You get upgrades for free and keep your column/label tweaks in one place. Same for the models — if you need scopes or accessors, extend the upstream Visitor/Session rather than editing vendor code.

Cache the aggregates. Analytics dashboards are the classic N+1-by-default screen. Wrap widget queries in Cache::remember() with a short TTL (60–300s); nobody needs second-fresh visitor counts, and it keeps a crowded dashboard from hammering the sessions table on every poll.

Watch the table sizes. Sessions and page views grow fast. Before shipping, confirm the upstream migrations index the foreign keys and the timestamp columns you filter on. If they don't, add an index in your own migration — this is the single most common reason these dashboards get slow after a few months.

Gotchas and Tips

The 0.0.x caret trap — read this twice. Composer's caret operator behaves differently below 1.0:

So ^0.0.2 pins you to exactly the 0.0.2 patch line — 0.0.3 and later are excluded. This is precisely the bug v0.1.1 fixed (v0.1.0's ^0.0.1 excluded 0.0.2, the first version with the relations). The pattern will bite you again: when upstream ships 0.0.3 with a fix you need, composer update will quietly refuse to go there. Either bump the constraint yourself in a fork/PR, or pin explicitly with "sergeybruhin/laravel-analytics": "0.0.*" in your root composer.json if you accept the instability.

Diagnose dependency failures with composer why-not. If the resources throw on a missing relation, don't read the package source first — run:

composer why-not sergeybruhin/laravel-analytics 0.0.2

That tells you whether Composer's constraint or another package is holding you back. It is far faster than reasoning about the lockfile by hand.

Verify the relation exists before blaming the package. In php artisan tinker:

method_exists(App\Models\Visitor::class, 'sessions');   // or the vendor model

false means you're on 0.0.1 and the fix is a dependency bump, not a code change. This is the fastest triage for the class of bug this release addresses.

Fresh installs are clean; upgrades aren't. If you added this package at v0.1.0 before 0.0.2 existed, Composer resolved you to 0.0.1 and your composer.lock is stale. composer update sergeybruhin/laravel-analytics <vendor>/<this-package> — then re-run any upstream migrations in case 0.0.2 added columns alongside the relations.

Zero-cost upgrade, but read the diff anyway. v0.1.1 is a one-line constraint change with no code or migration changes, so it's safe to take immediately. But it also means the package's correctness now depends entirely on a transitive 0.0.x dependency — pin your lockfile in CI and review upstream patch releases yourself, because this package won't always signal them loudly.

Extension points worth knowing: the plugin's resource/widget registration array (swap in your subclasses), the published config (tables, per-page, default date range), and the model bindings if the package exposes them. If it doesn't expose model bindings, subclassing the resource's getEloquentQuery() or applying a global scope on the upstream models are your two escape hatches for multi-tenancy.