Laravel Gtag

https://github.com/jeffersongoncalves/laravel-gtag
Admin
Laravel Gtag is a Laravel package that integrates Google Analytics (gtag.js) into Blade templates...
Tokens:5,853
Snippets:43
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-gtag package

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

Install the package via Composer, publish the settings migrations, and run migrations to set up the database tables.

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

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

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

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

Commands to run the test suite, generate coverage, run static analysis with PHPStan, and format code with Pint. Use these in the project root after installing dependencies.

```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
```

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

### Install laravel-gtag via Composer

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

Install the package via Composer.

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

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

### Publish and run gtag settings migrations

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

Publishes and runs the settings migration that creates entries in the `settings` table under the `gtag` group. Run these commands after installing the package to set up the database schema.

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

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

### Gtag facade usage

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

Facade usage example. The Gtag facade resolves to GtagSettings::class and is auto-aliased. Shows documented properties and how to get the underlying instance via getFacadeRoot().

```php
use JeffersonGoncalves\Gtag\Facades\Gtag;

// Documented properties on the facade
// @property ?string $gtag_id
// @property bool $enabled
// @property bool $anonymize_ip
// @property array $additional_config

Gtag::getFacadeRoot(); // returns GtagSettings instance
```

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

### Configure TestCase with seeded default settings

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

TestCase setup for the gtag package using Orchestra Testbench. Registers the LaravelSettingsServiceProvider and GtagServiceProvider, and seeds default settings directly via the DB facade instead of using SettingsMigrator. The settings table schema includes id, group, name, locked, payload, and timestamps.

```php
namespace JeffersonGoncalves\Gtag\Tests;

use JeffersonGoncalves\Gtag\GtagServiceProvider;
use Orchestra\Testbench\TestCase as Orchestra;
use Spatie\LaravelSettings\LaravelSettingsServiceProvider;

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

    protected function seedDefaultSettings(): void
    {
        $defaults = [
            ['group' => 'gtag', 'name' => 'gtag_id', 'payload' => json_encode(null)],
            ['group' => 'gtag', 'name' => 'enabled', 'payload' => json_encode(true)],
            ['group' => 'gtag', 'name' => 'anonymize_ip', 'payload' => json_encode(false)],
            ['group' => 'gtag', 'name' => 'additional_config', 'payload' => json_encode([])],
        ];

        foreach ($defaults as $setting) {
            DB::table('settings')->insert(
                array_merge($setting, [
                    'created_at' => now(),
                    'updated_at' => now(),
                ])
            );
        }
    }
}
```

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

### Publish and run settings migrations

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

Publish and run the settings migrations required for the package.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan vendor:publish --tag=gtag-settings-migrations
php artisan migrate
```

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

### Run tests with composer test

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

Run the package tests.

```bash
composer test
```

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

### Configure Gtag settings via code

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

Update settings at any time using the GtagSettings class, the gtag_settings() helper, or the Gtag facade.

```php
use JeffersonGoncalves\Gtag\Settings\GtagSettings;

// Via container
$settings = app(GtagSettings::class);
$settings->gtag_id = 'G-XXXXXXXXXX';
$settings->enabled = true;
$settings->save();

// Via helper
gtag_settings()->gtag_id = 'G-XXXXXXXXXX';
gtag_settings()->save();

// Via Facade
use JeffersonGoncalves\Gtag\Facades\Gtag;

$gtag = Gtag::getFacadeRoot();
$gtag->gtag_id = 'G-XXXXXXXXXX';
$gtag->save();
```

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

### Accessing and updating GtagSettings

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

Shows multiple ways to access the GtagSettings instance: via the global helper gtag_settings(), the Laravel container, or the Gtag facade. Also demonstrates updating properties and persisting with save().

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

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

// Via Facade
use JeffersonGoncalves\Gtag\Facades\Gtag;
$root = Gtag::getFacadeRoot(); // returns GtagSettings instance

// Update and persist
$settings->gtag_id = 'G-XXXXXXXXXX';
$settings->enabled = true;
$settings->anonymize_ip = true;
$settings->additional_config = [
    'send_page_view' => false,
    'cookie_domain' => 'example.com',
];
$settings->save();
```

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

### Package structure tree

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

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

```text
laravel-gtag/
├── src/
│   ├── GtagServiceProvider.php      # Package service provider
│   ├── Facades/Gtag.php            # Facade for GtagSettings
│   ├── Settings/GtagSettings.php    # Settings class (spatie/laravel-settings)
│   └── helpers.php                  # gtag_settings() helper function
├── database/
│   └── settings/
│       └── 2026_02_20_000000_create_gtag_settings.php
├── resources/
│   └── views/
│       └── script.blade.php         # Google Analytics tracking script template
└── tests/
    ├── TestCase.php                 # Base test case with SQLite setup
    ├── Pest.php                     # Pest configuration
    └── GtagSettingsTest.php         # Settings and view rendering tests
```

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

### Test GtagSettings defaults and persistence with Pest

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

Pest test pattern for the GtagSettings class. Verifies container resolution, default values (gtag_id null, enabled true, anonymize_ip false, additional_config empty array), and persistence of updated settings. Uses the `app()` helper to resolve the settings instance.

```php
use JeffersonGoncalves\Gtag\Settings\GtagSettings;

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

it('has correct default values', function () {
    $settings = app(GtagSettings::class);
    expect($settings->gtag_id)->toBeNull()
        ->and($settings->enabled)->toBeTrue()
        ->and($settings->anonymize_ip)->toBeFalse()
        ->and($settings->additional_config)->toBe([]);
});

it('persists updated settings', function () {
    $settings = app(GtagSettings::class);
    $settings->gtag_id = 'G-TESTID123';
    $settings->save();

    $fresh = app(GtagSettings::class);
    expect($fresh->gtag_id)->toBe('G-TESTID123');
});
```

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

### Set additional config for gtag

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

Set additional configuration parameters for gtag('config', ...).

```php
$settings = gtag_settings();
$settings->additional_config = [
    'send_page_view' => false,
    'cookie_domain' => 'example.com',
];
$settings->save();
```

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

### GtagSettings class definition

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

Defines the GtagSettings class extending Spatie\LaravelSettings\Settings with group 'gtag'. Properties include gtag_id, enabled, anonymize_ip, and additional_config with defaults as noted in comments.

```php
namespace JeffersonGoncalves\Gtag\Settings;

use Spatie\LaravelSettings\Settings;

class GtagSettings extends Settings
{
    public ?string $gtag_id;        // Google measurement ID (e.g., 'G-XXXXXXXXXX')
    public bool $enabled;            // Enable/disable tracking (default: true)
    public bool $anonymize_ip;       // Anonymize visitor IP addresses (default: false)
    public array $additional_config;  // Extra gtag config parameters (default: [])

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

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

### Configure gtag.js additional_config parameters

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

Sets the `additional_config` array on the gtag settings object. Supports any valid gtag.js configuration parameter, such as `send_page_view`, `cookie_domain`, `cookie_flags`, and `linker`. Save the settings after assigning the array.

```php
$settings = gtag_settings();
$settings->additional_config = [
    'send_page_view' => false,       // Disable automatic page view
    'cookie_domain' => 'example.com', // Set cookie domain
    'cookie_flags' => 'SameSite=None;Secure',
    'linker' => ['domains' => ['example.com', 'app.example.com']],
];
$settings->save();
```

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

### Test gtag Blade view rendering with Pest

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

Pest test pattern for the Blade view `gtag::script`. Verifies that the script renders when enabled with a valid gtag_id, does not render when disabled, includes `anonymize_ip` when enabled, and includes `additional_config` parameters. Each test sets settings, saves, renders the view, and asserts on the output.

```php
it('renders script when enabled with valid gtag_id', function () {
    $settings = app(GtagSettings::class);
    $settings->gtag_id = 'G-TESTID123';
    $settings->enabled = true;
    $settings->save();

    $view = view('gtag::script')->render();
    expect($view)
        ->toContain('googletagmanager.com/gtag/js?id=G-TESTID123')
        ->toContain("gtag('config', 'G-TESTID123')");
});

it('does not render script when disabled', function () {
    $settings = app(GtagSettings::class);
    $settings->gtag_id = 'G-TESTID123';
    $settings->enabled = false;
    $settings->save();

    $view = view('gtag::script')->render();
    expect($view)->not->toContain('googletagmanager.com');
});

it('renders anonymize_ip when enabled', function () {
    $settings = app(GtagSettings::class);
    $settings->gtag_id = 'G-TESTID123';
    $settings->enabled = true;
    $settings->anonymize_ip = true;
    $settings->save();

    $view = view('gtag::script')->render();
    expect($view)->toContain('"anonymize_ip":true');
});

it('renders additional_config parameters', function () {
    $settings = app(GtagSettings::class);
    $settings->gtag_id = 'G-TESTID123';
    $settings->enabled = true;
    $settings->additional_config = ['send_page_view' => false];
    $settings->save();

    $view = view('gtag::script')->render();
    expect($view)->toContain('"send_page_view":false');
});
```

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

### GtagServiceProvider registration

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

Service provider registration code from GtagServiceProvider. It registers views, adds GtagSettings to the spatie/laravel-settings config, publishes migrations with tag 'gtag-settings-migrations', and loads migrations directly.

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

// Registers GtagSettings in spatie/laravel-settings config
$settings = Config::get('settings.settings', []);
$settings[] = GtagSettings::class;
Config::set('settings.settings', $settings);

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

// Also loads migrations directly
$this->loadMigrationsFrom($migrationPath);
```

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

### Rendered gtag.js HTML snippet

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

The rendered gtag.js snippet. It includes the async script tag and the inline script that initializes dataLayer and sends a page view with anonymize_ip and send_page_view config. Rendering rules: only when enabled is true and gtag_id is not empty; anonymize_ip adds config; additional_config merged; empty config omits third argument; JSON encoded with JSON_UNESCAPED_SLASHES.

```html
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'G-XXXXXXXXXX', {"anonymize_ip":true,"send_page_view":false});
</script>
```

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

### Include Gtag script in Blade layout

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

Add the Gtag script to your Blade layout, typically in the <head> section.

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