Analytics Google Filament Laravel Package

Getting Started

Confirm what you're actually installing first. This is a presentation adapter — it almost certainly does not talk to Google directly. Expect it to require a sibling data package (something like liberusoftware/analytics-google) that wraps the GA4 Data API client, with this package contributing Filament widgets/pages/resources on top. Read composer.json require and require-dev before running anything; that tells you the true dependency graph in ten seconds.

Minimal setup:

composer require liberusoftware/analytics-google-filament
php artisan vendor:publish --provider="Liberu\Analytics\Google\Filament\AnalyticsGoogleFilamentServiceProvider"

Then, in order:

1. Service provider — src/Providers/*ServiceProvider.php. Check register() for container bindings (the adapter will bind an interface to a GA4 implementation) and boot() for Filament asset/component registration. Note whether panel registration is automatic or you must call something like ->plugin(AnalyticsGoogleFilamentPlugin::make()) on your PanelProvider.
2. Config file — config/analytics-google.php (or similar). This is where credentials, property ID, cache TTL, and date-range defaults live. Publish and read it top to bottom; it is the real API surface of the package.
3. Filament namespace — src/Filament/Widgets/ and src/Filament/Resources/. Enumerate the widget classes available; that's your menu of ready-made deliverables.
4. Migrations — if present, they'll map GA4 properties to tenants/teams. Run them and inspect the schema.

First use case: put a traffic-overview widget on an existing panel dashboard.

// app/Filament/Pages/Dashboard.php  (or your PanelProvider's widgets())
protected function getHeaderWidgets(): array
{
    return [
        \Liberu\Analytics\Google\Filament\Filament\Widgets\SessionsOverview::class,
    ];
}

Set GOOGLE_ANALYTICS_PROPERTY_ID (and service-account credentials) in .env before loading the dashboard, or you'll get an opaque exception during render rather than a clear config error.

Implementation Patterns

Separate data from presentation — and respect the seam. The package's value is that it renders; the sibling package fetches. When you need something the widgets don't do, don't fork the widget — inject the underlying client/service from the container and build your own Filament widget around it. That keeps upgrades cheap.

Per-tenant property mapping. In a multi-tenant panel the single property_id config is a trap. The idiomatic pattern is to resolve the property at request time from the current tenant/team:

// In your own widget extending the package's base widget
protected function getPropertyId(): string
{
    return tenant()->ga4_property_id
        ?? config('analytics-google.property_id');
}

If the package ships a resource for property→tenant mapping, prefer it over a custom column; you inherit the validation and the settings UI for free.

Cache aggressively; the GA4 API is the bottleneck. Wrap widget data in Cache::remember() with a TTL keyed on property + date range + metric set. A dashboard with six widgets should generate one or two API calls, not six. If the package exposes a cache TTL config key, set it per-environment: seconds in local, 15–60 minutes in production.

Push heavy reporting to a scheduled job. For anything beyond "last 7 days," don't call GA4 on page load. Sync into local tables on a schedule (php artisan schedule:run → a command from the data package) and let the Filament widgets read local data. This is the difference between a dashboard that loads in 200ms and one that times out during a Google quota incident.

Compose widgets rather than duplicating them. Most Filament analytics widgets expose a getStats()/getData()-style method. Subclass, override the query shaping, keep the rendering. Add filters with Filament's HasFilters / InteractsWithPageFilters on the page and pass the resolved date range down — don't hardcode ranges inside widget subclasses.

Testing. Bind a fake implementation of the analytics contract in your test suite, or Http::fake() the GA4 endpoint. Widget tests should assert on structure (assertSee, livewire(...)->assertOk()), never on live numbers.

Gotchas and Tips

License is NOASSERTION — resolve this before shipping. GitHub could not detect a standard license. For a zero-star, zero-dependent package in a commercial codebase, get written clarification or vendor the code into your repo under your own review. Also check whether the license header in src/ contradicts the root LICENSE file.

The release date reads as 2026-10-27, which is ahead of any sensible "now." Treat version metadata as unreliable: pin an exact version in composer.json, commit your composer.lock, and diff every upgrade. With 0 stars and 0 dependents there is no community canary — you are the QA.

GA4 credentials are the #1 failure mode. You need a service account added as a Viewer on the GA4 property, the Google Analytics Data API enabled in the GCP project, and analytics.readonly scope. A missing API enablement produces a 403 that looks identical to a permissions problem. Test the credential path independently of Filament before blaming the package.

Quota and sampling. The GA4 Data API has per-property token quotas. A dev refreshing a dashboard fifty times will exhaust them. Symptom: widgets silently render empty or throw 429s mid-development. Check storage/logs/laravel.log for the underlying HTTP exception — Filament will often swallow it into an empty state.

Timezone mismatch is silent and common. Filament/config('app.timezone') vs the GA4 property's reporting timezone will shift every date-range boundary. "Today" can mean two different days. Set the property timezone explicitly and convert, or accept a known offset documented in your codebase.

Filament version coupling is strict. Verify the package targets your Filament major (v3 vs v4 differ substantially in widget and panel APIs). Asset registration in boot() is the usual breakage point after upgrading — the widget class loads but styles/charts don't render. If widgets appear unstyled, that's the first place to look.

Panel registration order matters. Registering the plugin after your panel's ->widgets() call, or registering widgets from a plugin's boot(), can yield widgets that 404 on their Livewire route. Follow whatever example the README gives exactly, then experiment.

Debugging lever: if data looks wrong, dump the resolved query parameters (property, metrics, dimensions, date range) immediately before the HTTP call. Nine times out of ten the adapter is fine and the dimension/metric combination is invalid for the report type you asked for — GA4 rejects certain pairings with a 400 that the UI hides.

Extension points worth knowing: the container binding for the analytics client interface (swap for a fake in tests), the published config (all tuning lives there), and widget subclassing (safe). Avoid editing vendor/ — with no upstream community, your local patch will be lost on the next composer update and nobody will upstream a fix for you.