Laravel Metrics GA4

Laravel package to read Google Analytics 4 metrics through the GA4 Data API: visitors, sessions, pageviews, bounce rate, session duration, top pages, sources, countries, browsers, devices and realtime users — for dashboards, reports and automations.

Authentication uses a Google Cloud service account (JWT signed locally with OpenSSL, no Google SDK). Access tokens are cached until they expire.

Settings are stored in the database via spatie/laravel-settings — no config files needed. The service account key is stored encrypted.

Looking to add the gtag.js tracking script to your Blade layout instead? Use jeffersongoncalves/laravel-ga4.

Installation

composer require jeffersongoncalves/laravel-metrics-ga4

Run migrations to create the settings:

php artisan migrate

Google Cloud setup

1. In Google Cloud Console, enable the Google Analytics Data API for a project.
2. Create a service account and download a JSON key for it.
3. In Google Analytics, open Admin → Property access management and add the service account's client_email with the Viewer role.
4. Copy the numeric Property ID from Admin → Property details.

Configuration

After migration, the settings are seeded from environment variables:

GA4_PROPERTY_ID=123456789
GA4_SERVICE_ACCOUNT_JSON='{"type":"service_account","client_email":"...","private_key":"..."}'

You can also update settings programmatically:

use JeffersonGoncalves\MetricsGA4\Settings\GA4Settings;

$settings = app(GA4Settings::class);
$settings->property_id = '123456789';
$settings->service_account_json = file_get_contents(storage_path('app/ga4-key.json'));
$settings->save();

Usage

use JeffersonGoncalves\MetricsGA4\Facades\GA4;

Every method takes an optional $propertyId as its last argument, defaulting to the configured property. $days counts back from today (inclusive): 30 = the last 30 days, 1 = today.

Aggregate totals

$stats = GA4::aggregate();

$stats->visitors();       // 1234  (activeUsers)
$stats->visits();         // 1500  (sessions)
$stats->pageviews();      // 4321  (screenPageViews)
$stats->bounceRate();     // 41.5  (bounceRate, as a percentage)
$stats->visitDuration();  // 96.0  (averageSessionDuration, seconds)

// Pick metrics and period
$stats = GA4::aggregate(['visitors', 'pageviews'], days: 7);

Package metric names map to GA4 metrics: visitors → activeUsers, visits → sessions, pageviews → screenPageViews, bounce_rate → bounceRate, visit_duration → averageSessionDuration. Any other value is passed through as a raw GA4 metric name.

Timeseries

// Daily visitors and pageviews over the last 30 days
foreach (GA4::timeseries() as $row) {
    echo $row->label.': '.$row->visitors();  // 2026-09-01: 120
}

Breakdowns

$pages = GA4::pages(days: 30, limit: 10);      // pagePath
$sources = GA4::sources();                      // sessionSource
$countries = GA4::countries();                  // country
$browsers = GA4::browsers();                    // browser
$devices = GA4::devices();                      // deviceCategory

foreach ($pages as $row) {
    echo $row->label;                  // /blog/hello-world
    echo $row->visitors();             // 90
    echo $row->metric('pageviews');    // 120
}

// Any other GA4 dimension
$rows = GA4::breakdown('city', days: 7, metrics: ['visitors', 'visits']);

Realtime

$visitors = GA4::realtimeVisitors();  // active users in the last 30 minutes

Raw reports

$response = GA4::runReport([
    'dateRanges' => [['startDate' => '2026-01-01', 'endDate' => '2026-01-31']],
    'dimensions' => [['name' => 'landingPage']],
    'metrics' => [['name' => 'conversions']],
]);

Error Handling

Testing

composer test

Code Style

composer format

Static Analysis

composer analyse

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• All Contributors

License

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