Fathom Laravel Package

Getting Started

This is a single-purpose addon: it registers a control-panel nav entry that deep-links out to the Fathom dashboard for a configured site. Treat it as a convenience shortcut, not an analytics integration — there is no API client, no chart rendering, and no data pulled back into Statamic.

Minimal setup:

1. composer require aerni/fathom. Note the v1.2.0 constraint: it requires Statamic 5 and drops Statamic 4. If you're still on Statamic 4, composer will resolve to the older 1.1.x line instead — decide deliberately, don't let it drift.
2. Publish the config (php artisan vendor:publish --tag=fathom-config or via the addon's publish tag — check php artisan vendor:publish output, the tag names are not documented prominently).
3. Open config/statamic/fathom.php. The two things that matter are the site ID and, if you are not on Fathom Cloud, the base URL of your instance. Wire both to .env values rather than hardcoding.
4. php artisan config:clear (or config:cache in production) and reload the CP. A "Fathom" item should appear in the nav.

First real use case: an editor finishes a landing page, clicks the nav item, and lands on that site's Fathom dashboard in one hop instead of hunting for a bookmark. That is the whole value proposition — evaluate it on that basis.

Before rolling it out, confirm Statamic version compatibility in composer.json. As of v1.2.0 the package targets Statamic 5 only; Statamic 4 installs are stuck on the 1.1.x line and should pin accordingly. Also confirm the nav item shows up for the roles you expect.

Implementation Patterns

Environment-scoped site IDs. Keep the site ID in .env per environment. Staging and production almost always have different Fathom sites (or you only track production), and a hardcoded ID in a committed config file is the most common way this addon silently links to the wrong dashboard.

Multi-site installs. If you run Statamic multisite, decide whether a single global site ID is acceptable or whether each Statamic site needs its own target. If the config only exposes one ID, the cheapest path is a small service provider override or a config/statamic/fathom.php that resolves from the current site handle — but verify the addon reads config at render time, not at boot, before relying on that.

Self-hosted Fathom. The base URL is the important knob here. Point it at your instance (e.g. https://fathom.internal) and confirm the resulting link includes the right path prefix. This is the pattern most likely to break quietly, because a wrong host still produces a clickable link — it just 404s.

Pair it with the tracking side. If you also inject the Fathom script into your front end, keep the site ID in one place (one env var, referenced from both the front-end snippet config and this addon's config) so the link and the tracking can never drift apart.

Treat it as a CP-only, permissioned affordance. Because it's just a link, the main governance question is who sees it. Check whether the nav item respects Statamic's permission system; if it appears for roles that don't have Fathom accounts, it's noise that will generate support tickets. Either scope it to an editor/admin role or accept that it's visible to everyone.

Statamic 4 → 5 upgrade choreography. If you're moving the app to Statamic 5, this addon is effectively a free upgrade — do the Statamic 5 bump and let composer pull aerni/fathom ^1.2. If you're staying on Statamic 4 for now, pin aerni/fathom to ^1.1 explicitly so a composer update doesn't try to drag the app forward or fail resolution confusingly.

Deployment checklist. Add the site ID env var to your deploy secrets for every environment, make sure config:cache runs after it's present, and pin the addon version line (1.2.x on Statamic 5, 1.1.x on Statamic 4) so environment builds are reproducible. A cached config from an earlier deploy is the usual reason "the link goes to the old site".

Gotchas and Tips

• It is a link, not a dashboard. Users leave Statamic and land in Fathom, where they need their own Fathom login. There is no SSO passthrough. Set that expectation with editors up front or you'll get "it asked me to sign in" bug reports.
• "Shared site" is the operative term. If the configured Fathom site isn't shared with (or accessible to) the logged-in user, the deep link lands on an error or an empty state. The addon can't detect this — it just builds a URL.
• Config caching bites. In production, changing the site ID without re-caching config has no effect. Always php artisan config:cache after editing env values, and config:clear locally when the link looks stale.
• Version constraints tightened in v1.2.0. Support for Statamic 5 was added and Statamic 4 support was dropped in the same release. Read the composer.json constraint before upgrading: on a Statamic 4 app, blindly running composer update either leaves you on 1.1.x or surfaces a resolution conflict you'll have to reason about. Pin the major version line you actually want.
• Low-traffic package, so pin and verify. Zero dependents, small maintainer surface. The v1.2.0 release is a good sign of life, but the feature set hasn't grown — it's still just a link. Pin the version, and re-run your CP smoke test after each Statamic minor upgrade (the nav registration API has shifted across Statamic majors before). The surface area is small enough that a fork remains a realistic option if it stalls again.
• Debugging a missing nav item: check the addon is actually discovered (php artisan about or the addons list in the CP), that the config file was published to the right path, and that your user's role has CP access. A blank config file usually means the publish step silently did nothing because the tag was wrong.
• Debugging a wrong URL: inspect the rendered href in the CP. That single string tells you whether the problem is the site ID, the base URL, or a path prefix — you don't need to read the source.
• Extension points are essentially nil. No events, no API, no view you're expected to override. If you need per-site links, a custom label, or a second analytics provider link, plan on overriding the config or forking rather than composing. v1.2.0 changed nothing about this.
• Don't mistake it for the tracking addon. If you were hoping this package also injects the Fathom script, it doesn't — budget a separate solution for front-end tracking and keep the site ID shared between them.