README

Laravel Metrics Fathom

Laravel package to interact with the Fathom Analytics API. Fetch pageviews, visitors, events, milestones, and generate custom aggregation reports.

Settings are stored in the database via spatie/laravel-settings — no config files needed.

Installation

composer require jeffersongoncalves/laravel-metrics-fathom

Run migrations to create the settings:

php artisan migrate

Configuration

After migration, the settings are seeded from environment variables:

FATHOM_API_TOKEN=your-api-token
FATHOM_SITE_ID=your-site-id
FATHOM_BASE_URL=https://api.usefathom.com/v1
FATHOM_TIMEZONE=UTC

You can also update settings programmatically:

use JeffersonGoncalves\MetricsFathom\Settings\FathomSettings;

$settings = app(FathomSettings::class);
$settings->api_token = 'new-token';
$settings->site_id = 'NEWSITE';
$settings->timezone = 'America/Sao_Paulo';
$settings->save();

Usage

Using the Facade

use JeffersonGoncalves\MetricsFathom\Facades\Fathom;

Account

$account = Fathom::account();

Sites

// List sites
$result = Fathom::sites(limit: 20);
foreach ($result['data'] as $site) {
    echo $site->id . ' - ' . $site->name;
}

// Get a site
$site = Fathom::site('SITEID');

// Create a site
use JeffersonGoncalves\MetricsFathom\Enums\Sharing;
$site = Fathom::createSite('My Site', Sharing::Public);

// Update a site
$site = Fathom::updateSite('SITEID', name: 'New Name');

// Delete a site
Fathom::deleteSite('SITEID');

Events

// List events
$result = Fathom::events();

// Create an event
$event = Fathom::createEvent('signup');

// Get an event
$event = Fathom::event('EVENTID');

// Update an event
$event = Fathom::updateEvent('EVENTID', 'new-name');

// Delete an event
Fathom::deleteEvent('EVENTID');

Milestones

// List milestones
$result = Fathom::milestones();

// Create a milestone
$milestone = Fathom::createMilestone('v2.0 Launch', '2026-03-01');

// Update a milestone
$milestone = Fathom::updateMilestone('MSID', name: 'v2.1 Launch');

// Delete a milestone
Fathom::deleteMilestone('MSID');

Current Visitors

// Simple count
$visitors = Fathom::currentVisitors();
echo $visitors->total; // 42

// Detailed (top pages & referrers)
$visitors = Fathom::currentVisitors(detailed: true);

Aggregations (Custom Reports)

Build flexible reports using the fluent query builder:

use JeffersonGoncalves\MetricsFathom\Enums\Aggregate;
use JeffersonGoncalves\MetricsFathom\Enums\DateGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\FieldGrouping;
use JeffersonGoncalves\MetricsFathom\Enums\FilterOperator;

// Pageviews per day for the last month
$query = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Pageviews, Aggregate::BounceRate)
    ->groupByDate(DateGrouping::Day)
    ->from('2026-02-01 00:00:00')
    ->to('2026-02-28 23:59:59');

$result = Fathom::aggregate($query);

// Top pages by visits
$query = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->groupByField(FieldGrouping::Pathname)
    ->sortBy('visits', 'desc')
    ->limit(10);

$result = Fathom::aggregate($query);

// Visitors by country
$query = Fathom::query()
    ->aggregate(Aggregate::Uniques)
    ->groupByField(FieldGrouping::CountryCode)
    ->sortBy('uniques', 'desc');

$result = Fathom::aggregate($query);

// Filter by UTM source
$query = Fathom::query()
    ->aggregate(Aggregate::Visits, Aggregate::Uniques)
    ->where(FieldGrouping::UtmSource, FilterOperator::Is, 'twitter')
    ->from('2026-01-01 00:00:00');

$result = Fathom::aggregate($query);

// Event conversions
$query = Fathom::queryEvents()
    ->aggregate(Aggregate::Conversions, Aggregate::UniqueConversions)
    ->forSite('SITEID')
    ->forEvent('signup')
    ->groupByDate(DateGrouping::Month);

$result = Fathom::aggregate($query);

Using DateTime Objects

use Carbon\Carbon;

$query = Fathom::query()
    ->aggregate(Aggregate::Visits)
    ->between(Carbon::now()->subDays(30), Carbon::now());

$result = Fathom::aggregate($query);

Available Enums

Aggregate

Visits, Uniques, Pageviews, AvgDuration, BounceRate, Conversions, UniqueConversions, Value

DateGrouping

Hour, Day, Month, Year

FieldGrouping

Hostname, Pathname, ReferrerHostname, Referrer, Browser, BrowserVersion, CountryCode, City, DeviceType, OperatingSystem, OperatingSystemVersion, UtmSource, UtmMedium, UtmCampaign, UtmContent, UtmTerm

FilterOperator

Is, IsNot, IsLike, IsNotLike, Matching, NotMatching

Sharing

None, Private, Public

API Rate Limits

• Sites & Events: 2,000 requests/hour
• Aggregations & Current Visitors: 10 requests/minute

Testing

composer test

Code Style

composer format

Static Analysis

composer analyse

License

The MIT License (MIT). Please see License File for more information.