Fathom Api Laravel Package

Product Decisions This Supports

• Build vs. buy for analytics reporting. Rather than building a bespoke reporting stack, a Laravel team can buy Fathom as the privacy-first analytics backend and use this thin, fluent client to pull aggregate traffic data into the app. The 1.1.0 release — which adds Fathom v3 compatibility — is the signal that the client points at a current API surface, not a deprecated one. Weigh internal build effort against a Composer dependency with a single-maintainer profile.
• Privacy and compliance roadmap. Standardizing on Fathom reduces cookie-banner dependency and third-party tracking exposure. This package is the in-app retrieval layer that makes that privacy posture usable inside admin panels and back offices — the difference between "we chose a privacy-friendly vendor" and "we actually surface its data without an iframe."
• Dashboard and client-reporting scope. Enables admin panels, client portals, and internal KPI views to show pageviews, visitors, referrers, and country breakdowns without sending users into the Fathom UI. Drives the decision of what reporting we expose, and to whom — internal operators vs. external clients.
• Feature boundary setting. The package covers aggregate reporting only — no funnels, cohorts, retention, session replay, or user-level event streams. That boundary belongs in the product spec up front so stakeholders don't expect product analytics from a traffic-reporting integration.
• Vendor and maintenance risk gating. With 0 stars, 0 dependents, and a 0.3 package score, adoption signal is effectively absent. 1.1.0 is a real maintenance signal but not a cadence or a track record. Suitable for a time-boxed spike or low-risk internal tooling; not a strategic dependency without engineering sign-off.
• Roadmap sequencing for existing Fathom v2 users. If Fathom is already in the stack at v2, the v3 upgrade is its own scoped item — regression testing plus an explicit answer on whether 1.1.0 is additive or breaking — before rolling forward. Do not bundle it with a feature release.
• Resilience-by-design decisions. Because the Fathom API is comparatively slow and rate-limited, the product decision isn't "do we show live stats" but "do we accept a cached, nightly-snapshot model." That choice should be made at spec time, not discovered in production by a throttled dashboard.
• Data retention strategy. A nightly snapshot job into a local analytics_daily table gives us history that outlives Fathom's own retention window and lets us backfill or repair without touching the vendor. That's a product-level durability decision, not just an engineering pattern.

When to Consider This Package

Consider it when:

• The application is Laravel/PHP and is already using, or committed to adopting, Fathom Analytics v3.
• You need server-side retrieval of aggregate analytics for internal dashboards, client reports, or lightweight embedded stats — not product telemetry.
• You want a small convenience wrapper (published config, service provider, Fathom facade / DI access, fluent site→metric→date-range calls returning arrays) rather than hand-rolling and maintaining a Fathom HTTP client.
• The use case is non-critical reporting, where caching, graceful degradation, and a manual fallback are acceptable failure modes.
• You can isolate the package behind an internal interface (e.g., an AnalyticsReport adapter) so the facade never leaks into controllers or Blade and the vendor stays replaceable with a one-line container binding.
• You are willing to pin an exact version (1.1.0, not ^1.1) and track the repo and Fathom's v3 changelog, with a fork or in-house client as a pre-planned escape hatch.
• You can resolve site IDs once at config/seed time and store them, rather than doing name lookups on a request path — the documented firstWhere('name', ...) pattern fails silently on renames.

Look elsewhere when:

• You need product analytics — funnels, cohorts, retention, session replay, user-level event streams. This is a traffic-reporting client, not an analytics platform.
• You need event ingestion or site management. The builder exposes /sites, /aggregations, /events, /current_visitors; anything beyond aggregate reporting should be verified against Fathom's v3 docs before it's assumed to exist.
• Reporting is business-critical or customer-facing at scale, where an unmaintained dependency with zero dependents is an unacceptable single point of failure without an owned fork.
• The team is not on Laravel (the "framework-agnostic" claim still means Laravel's HTTP client and, on Lumen, manual provider/alias registration — a silent null-facade trap).
• You need typed, schema-validated responses. Everything returns plain arrays; map to DTOs at the boundary and log on missing keys, or a silent v3 response-shape change becomes a null in a widget with no error anywhere.
• You need guaranteed freshness. Set timeouts, retries with backoff and jitter, and a circuit breaker explicitly; verify v3 rate-limit behaviour rather than assuming v2 carried over.

How to Pitch It (Stakeholders)

For executives: We can ship privacy-friendly traffic reporting inside our own admin and client-facing dashboards without building an analytics backend. Fathom stays the system of record; this package is a small, replaceable adapter that pulls its numbers into our Laravel app. The strategic value is the privacy posture and the avoided build cost — not the package itself. Recommendation: approve as a scoped, low-risk integration behind our own interface, with an exact version pin and a quarterly dependency review. Do not treat it as a platform commitment.

For engineering: It's a thin fluent builder over Laravel's HTTP client — Fathom::site($id)->pageviews(from:, to:) returning plain arrays, with a published config and auto-discovered provider. That's the entire public surface. Two hard requirements before it goes anywhere near production: (1) wrap the facade in an AnalyticsReport interface so the vendor is a one-line container swap, and (2) never call Fathom live from a request path — run a nightly snapshot job into a local table and let dashboards read from the database. Everything is untyped, so map to DTOs at the boundary and log on missing keys as our early warning for API drift. Watch for the known traps: stale config:cache is the #1 cause of phantom 401s, base_url/API-version is the single most important config value, and name-based site lookup fails silently on rename.

The honest risk statement, stated once: zero stars, zero dependents, one release signal, no maintenance cadence. That doesn't disqualify it for internal reporting — it disqualifies it as an unexamined dependency. Pin it, isolate it, and have the fork ready.