Filament Pirsch Dashboard Widget Laravel Package

Getting Started

This package provides a Filament dashboard widget that surfaces Pirsch analytics data inside your admin panel, so you can review traffic without leaving the app.

1. Install via Composer: composer require devlogx/filament-pirsch-dashboard-widget
2. Publish/set config after install — run the package's install command (or vendor:publish for the config tag) and add your Pirsch credentials to .env (typically an access token / client ID plus the domain you want to report on). Keep these out of version control.
3. Register the widget in your Filament panel provider (->widgets([...])) or let it auto-register, then confirm the dashboard renders without errors.
4. First use case: drop the widget onto the default Dashboard page, load it as a super-admin, and verify the numbers match the Pirsch web UI for the same date range. That single check validates credentials, domain scoping, and caching behaviour in one go.

If the widget renders an empty state instead of data, the problem is almost always credentials or a domain mismatch, not the widget itself — check that first.

Implementation Patterns

• Panel scoping: register the widget only on the panel(s) that should see analytics. For multi-panel apps, guard it behind canView() so customer-facing panels never expose traffic data.
• Credential management: bind credentials through config (backed by .env) rather than constructor arguments. This keeps the widget compatible with config caching (php artisan config:cache) in production.
• Date ranges and filters: if the widget exposes a period selector, drive it from widget properties or Filament's filter state so the surrounding dashboard filters stay consistent. Avoid hardcoding a range in the widget class.
• Dashboard composition: pair the widget with a grid column span (->columnSpan()) and place it alongside your existing stats overview. Analytics widgets are usually wide — full width or two-thirds reads better than a quarter-width card.
• Caching: Pirsch API calls on every dashboard load will slow the panel and burn rate limits. Wrap reads in Cache::remember() with a short TTL (5–15 minutes) in a small service or custom widget subclass, and clear the cache key on deploy.
• Custom variants: if you need a different metric (referrers, pages, conversions), extend the shipped widget and override the data method rather than forking the package — this keeps composer update clean.
• Testing: in feature tests, fake the HTTP calls (Http::fake()) so widget rendering tests don't hit the Pirsch API, and assert the empty/error state renders gracefully.

Gotchas and Tips

• Release 1.1.1 is maintenance only. It fixes Spatie Package Tools scaffolding (service provider / config wiring). No breaking changes, no new features, no deprecations — upgrading from 1.1.0 is safe. It does mean the package's package-tools setup was previously misconfigured, so if you publish config or assets on an older version, re-publish after upgrading and diff the results.
• Publish tags matter. A broken package-tools setup often surfaces as a missing or stale config file. If config changes you make seem ignored, re-run vendor:publish --force for the package's tag and clear cached config.
• Config cache trap. Reading env() directly inside the widget works in local dev and silently returns null in production once config:cache runs. Always read through config().
• Silent empty states. API auth failures and "no data for this range" can look identical in the UI. Enable debug logging temporarily, or wrap the client call and log the HTTP status, so you can tell a 401 from a genuine zero-traffic day.
• Timezone and range edges. Analytics backends bucket by their own timezone. If today's numbers look low, check whether the widget's range is inclusive of the current partial day.
• Rate limits. Pirsch's API is metered per token; a dashboard left open on a wall monitor plus a short cache TTL is a common way to hit limits. Cache aggressively and share the cache key across panels.
• Extension points. Favourably, the widget is a standard Filament widget — you can subclass it, override the view, and use Laravel's container to swap in your own Pirsch client. Prefer that over editing vendor files.
• Watch the repo. Given this is a small, single-maintainer package, pin the major version (^1.1) and review changelogs on update; breaking changes are most likely to arrive as Filament major-version bumps rather than in the package's own API.