Laravel Fathom

https://github.com/jeffersongoncalves/laravel-fathom
Admin
Laravel Fathom is a Laravel package that integrates Fathom Analytics into Blade templates with...
Tokens:4,268
Snippets:39
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-fathom package

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Install the package and publish its settings migrations, then run migrations to create the Fathom settings table.

```bash
composer require jeffersongoncalves/laravel-fathom
php artisan vendor:publish --tag=fathom-settings-migrations
php artisan migrate
```

--------------------------------

### Install Laravel Fathom via Composer

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-fathom
```

--------------------------------

### Rendered Fathom script tag

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Example HTML output of the Fathom script tag with conditional data attributes. The script only renders when website_id is not empty; data-canonical appears only when canonical is false, data-spa only when spa is not null, data-honor-dnt only when true, and data-auto-track always renders as "true" or "false".

```html
<script src="https://cdn.usefathom.com/script.js" defer
        data-site="ABCDEFGH"
        data-spa="history"
        data-honor-dnt="true"
        data-auto-track="true">
</script>
```

--------------------------------

### Run tests, coverage, static analysis, and formatting

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Commands to run the test suite, generate coverage, run static analysis with PHPStan, and format code with Pint.

```bash
# Run all tests
vendor/bin/pest

# Run with coverage
vendor/bin/pest --coverage

# Run static analysis
vendor/bin/phpstan analyse

# Format code
vendor/bin/pint
```

--------------------------------

### Publish and Run Fathom Settings Migration

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Publish and run the settings migration to create the database table for Fathom settings.

```bash
php artisan vendor:publish --tag=fathom-settings-migrations
php artisan migrate
```

--------------------------------

### Run Tests with Composer

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Run the package test suite.

```bash
composer test
```

--------------------------------

### Package structure

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Shows the directory layout of the laravel-fathom package, including source files, migrations, views, and tests.

```text
laravel-fathom/
├── src/
│   ├── FathomServiceProvider.php    # Package service provider
│   ├── Facades/Fathom.php          # Facade for FathomSettings
│   ├── Settings/FathomSettings.php  # Settings class (spatie/laravel-settings)
│   └── helpers.php                  # fathom_settings() helper function
├── database/
│   └── settings/
│       └── 2026_01_01_000000_create_fathom_settings.php
├── resources/
│   └── views/
│       └── script.blade.php         # Fathom tracking script template
└── tests/
    ├── TestCase.php                 # Base test case with SQLite setup
    ├── Pest.php                     # Pest configuration
    ├── FathomSettingsTest.php       # Settings unit tests
    └── BladeViewTest.php            # Blade view rendering tests
```

--------------------------------

### Fathom facade usage

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Shows how to use the Fathom facade. The facade accessor returns the FathomSettings class string, and calling getFacadeRoot() returns a FathomSettings instance.

```php
use JeffersonGoncalves\Fathom\Facades\Fathom;

// The facade accessor returns the FathomSettings class string
Fathom::getFacadeRoot(); // returns FathomSettings instance
```

--------------------------------

### Set up Testbench TestCase with SQLite in-memory

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Base TestCase for package tests using Orchestra Testbench: registers the LaravelSettings and Fathom service providers, and configures an in-memory SQLite database for testing.

```php
namespace JeffersonGoncalves\Fathom\Tests;

use JeffersonGoncalves\Fathom\FathomServiceProvider;
use Orchestra\Testbench\TestCase as Orchestra;
use Spatie\LaravelSettings\LaravelSettingsServiceProvider;

class TestCase extends Orchestra
{
    protected function getPackageProviders($app): array
    {
        return [
            LaravelSettingsServiceProvider::class,
            FathomServiceProvider::class,
        ];
    }

    protected function defineEnvironment($app): void
    {
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
        ]);
    }
}
```

--------------------------------

### Accessing and updating FathomSettings

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Shows three ways to access FathomSettings: via the global helper fathom_settings(), via the Laravel container with app(), and how to update and persist settings using save().

```php
// Helper function (globally available)
$settings = fathom_settings();

// Via Laravel container
$settings = app(\JeffersonGoncalves\Fathom\Settings\FathomSettings::class);

// Update and persist
$settings->website_id = 'ABCDEFGH';
$settings->spa = 'history';
$settings->save();
```

--------------------------------

### Test FathomSettings defaults and persistence with Pest

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Pest tests for FathomSettings: verifying container resolution, default values (website_id null, canonical/auto true, spa/honor_dnt null), and persistence of a website_id update.

```php
use JeffersonGoncalves\Fathom\Settings\FathomSettings;

it('can resolve FathomSettings from the container', function () {
    $settings = app(FathomSettings::class);
    expect($settings)->toBeInstanceOf(FathomSettings::class);
});

it('has correct default values', function () {
    $settings = app(FathomSettings::class);
    expect($settings->website_id)->toBeNull()
        ->and($settings->canonical)->toBeTrue()
        ->and($settings->auto)->toBeTrue()
        ->and($settings->spa)->toBeNull()
        ->and($settings->honor_dnt)->toBeNull();
});

it('can update and persist settings', function () {
    $settings = app(FathomSettings::class);
    $settings->website_id = 'ABCDEFGH';
    $settings->save();

    $fresh = app(FathomSettings::class);
    expect($fresh->website_id)->toBe('ABCDEFGH');
});
```

--------------------------------

### Read and Update Fathom Settings via Facade

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Read and update Fathom settings through the Fathom facade. The facade resolves the underlying FathomSettings instance, so access properties via getFacadeRoot().

```php
use JeffersonGoncalves\Fathom\Facades\Fathom;

// Read a value
$websiteId = Fathom::getFacadeRoot()->website_id;

// Update and persist
$settings = Fathom::getFacadeRoot();
$settings->website_id = 'NEW_SITE_ID';
$settings->save();
```

--------------------------------

### Update Fathom Settings via Helper

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Update Fathom settings using the fathom_settings() helper function.

```php
$settings = fathom_settings();
$settings->website_id = 'NEW_SITE_ID';
$settings->save();
```

--------------------------------

### FathomSettings class definition

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Defines the FathomSettings class extending Spatie\LaravelSettings\Settings with group 'fathom'. Properties include website_id, canonical, auto, spa, and honor_dnt with defaults as noted in comments.

```php
namespace JeffersonGoncalves\Fathom\Settings;

use Spatie\LaravelSettings\Settings;

class FathomSettings extends Settings
{
    public ?string $website_id;  // Fathom site ID (e.g., 'ABCDEFGH')
    public bool $canonical;       // Use canonical URLs (default: true)
    public bool $auto;            // Auto-track page views (default: true)
    public ?string $spa;          // SPA mode: 'auto', 'history', 'hash', or null
    public ?bool $honor_dnt;      // Honor Do Not Track header

    public static function group(): string
    {
        return 'fathom';
    }
}
```

--------------------------------

### Update Fathom Settings via Container

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Update Fathom settings programmatically using the FathomSettings class resolved from the container.

```php
use JeffersonGoncalves\Fathom\Settings\FathomSettings;

$settings = app(FathomSettings::class);
$settings->website_id = 'NEW_SITE_ID';
$settings->spa = 'history';
$settings->save();
```

--------------------------------

### FathomServiceProvider registration

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Service provider code from FathomServiceProvider extending PackageServiceProvider. Registers views, merges FathomSettings into the settings config, and publishes migrations with the tag 'fathom-settings-migrations'.

```php
// Registers the package with views
$package->name('laravel-fathom')->hasViews();

// Automatically registers FathomSettings in spatie/laravel-settings config
Config::set('settings.settings', array_merge(
    Config::get('settings.settings', []),
    [FathomSettings::class]
));

// Publishes settings migrations with tag 'fathom-settings-migrations'
$this->publishes([
    $settingsMigrationsPath => database_path('settings'),
], 'fathom-settings-migrations');
```

--------------------------------

### Test Fathom Blade script rendering with Pest

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/resources/boost/skills/fathom-development/SKILL.md

Pest tests for the Blade view: verifies the script tag renders with the CDN URL and data-site attribute when website_id is set, and is omitted when website_id is empty.

```php
use JeffersonGoncalves\Fathom\Settings\FathomSettings;

it('renders the script tag when website_id is set', function () {
    $settings = app(FathomSettings::class);
    $settings->website_id = 'TESTSITE';
    $settings->save();

    $view = $this->blade('@include("fathom::script")');
    $view->assertSee('https://cdn.usefathom.com/script.js', false)
        ->assertSee('data-site="TESTSITE"', false);
});

it('does not render the script tag when website_id is empty', function () {
    $settings = app(FathomSettings::class);
    $settings->website_id = null;
    $settings->save();

    $view = $this->blade('@include("fathom::script")');
    $view->assertDontSee('cdn.usefathom.com', false);
});
```

--------------------------------

### Include Fathom Script in Blade Layout

Source: https://github.com/jeffersongoncalves/laravel-fathom/blob/master/README.md

Include the Fathom script in your Blade layout, typically in the <head> section.

```php
@include('fathom::script')
```
Tokens:
Raw