Fathom Stats Display Laravel Package

Getting Started

This is a small, single-maintainer package (3 stars, no dependents) that surfaces Fathom Analytics stats inside a Laravel app. Because the surface area is tiny and the documentation is thin, treat the source as the documentation.

1. Install and inspect before you configure.

   composer require charlielangridge/fathom-stats-display
   

   Then open vendor/charlielangridge/fathom-stats-display/ and read composer.json (Laravel/PHP version constraints), the service provider, and any config/ or resources/views/ directories. That is 10 minutes of work that will save you an hour of guessing.

2. Publish the config and views. Packages of this shape almost always ship a config file and Blade views:

   php artisan vendor:publish --provider="CharlieLangridge\FathomStatsDisplay\FathomStatsDisplayServiceProvider"
   

   If the provider name differs, run php artisan vendor:publish and pick the tagged entry interactively rather than guessing the FQCN.

3. Set credentials in .env. You will need a Fathom API token (Fathom account settings → API) and the numeric site ID:

   FATHOM_API_TOKEN=xxxxxxxxxxxxxxxxxxxx
   FATHOM_SITE_ID=123456789
   

   Confirm the exact key names against the published config — do not assume.

4. First use case: an internal stats page. The highest-value first integration is a single authenticated route rendering the package's default view. Wire it behind auth (and probably an admin gate) immediately:

   Route::middleware(['auth', 'can:view-analytics'])->group(function () {
       Route::get('/admin/analytics', fn () => view('analytics.dashboard'));
   });
   

   In analytics/dashboard.blade.php, include the package component/view. Verify the token is not present in the rendered HTML before you ship it.

Implementation Patterns

Wrap the package in your own view, not the other way around. Don't edit published package views in place; create resources/views/admin/analytics.blade.php that composes your layout and <x-fathom-stats ... /> (or @include the package view). This keeps upgrades cheap and lets you control the chrome around the stats.

Cache aggressively at the application layer. Fathom's API is rate-limited and you do not want a dashboard refresh to hit it per page load. Put a thin service in front of the package:

$stats = Cache::remember("fathom.stats.{$siteId}.{$range}", now()->addMinutes(30), function () use ($siteId, $range) {
    return app(FathomStats::class)->forSite($siteId)->range($range)->get();
});

If the package exposes its own caching config, use it — but keep a Cache::remember wrapper anyway so you control TTL and cache keys.

Multi-site support via config, not code. If you run several properties, keep a map in config/fathom.php ('sites' => ['marketing' => env('FATHOM_SITE_MARKETING'), ...]) and resolve site IDs by key. This avoids sprinkling env calls through views and makes tests trivial with config()->set().

Scheduled snapshots for anything you want to trend. Dashboards that query live are fine for today; anything historical should be an Artisan command that pulls and persists into a local analytics_snapshots table, scheduled in routes/console.php or Kernel::schedule(). That decouples your reporting from Fathom's API availability and from the package's continued existence.

Livewire / Inertia integration. For Livewire, bind the stats fetch to a computed property and let the component refresh; for Inertia, resolve the stats in the controller and pass as props so the API call never leaks to the client. Avoid calling the Fathom API from the browser — the token is a server-side secret.

Testing. Bind a fake implementation of whatever the package's client class is ($this->instance(...) or $this->mock(...)) so your feature tests don't hit the network. If the package isn't designed for that, isolate it behind your own AnalyticsRepository interface and fake that.

Gotchas and Tips

• Zero dependents is a real risk signal. With 3 stars, no dependents, and a single release, assume maintenance may stop. Wrap the package behind one interface or one Blade partial so removal is a 30-minute job, not a refactor.
• Never render the API token client-side. If the package ships any JavaScript or inline config, grep the compiled output for the token before deploying. Fathom tokens grant read access to your analytics.
• Check the Laravel version constraint hard. Small packages frequently pin illuminate/support tightly. Run composer why-not if install fails and consider --with-all-dependencies only after reading what it would change.
• Rate limits and 429s. Fathom's API will throttle you. If you see intermittent empty dashboards, it's almost certainly rate limiting, not a package bug — add caching and a retry with backoff.
• Timezone and date-range semantics are the usual source of "wrong numbers". Fathom reports in the site's configured timezone; your app may not. Normalise explicitly (e.g. ->range(Carbon::today()->subDays(29), Carbon::today())) and don't assume the package does it for you.
• Publishing views is a fork, not a merge. Once you publish and edit views, composer update won't bring view changes. Keep a note in your repo of what you changed, or override via your own partials instead.
• Extension points are limited by design. Expect to extend via config values, view overrides, and your own wrapper — not events or pipelines. Don't build an elaborate abstraction on top of a three-star package; build a thin one and keep the option to swap in a direct Fathom API call (GuzzleHttp + /api/v1/aggregations) if the package becomes a liability.
• Debugging tip: if the dashboard is blank rather than erroring, it's usually a swallowed exception from the HTTP client. Temporarily set APP_DEBUG=true locally and check storage/logs/laravel.log — most packages of this size log failures quietly and render an empty component.