spatie/laravel-analytics: Reading GA4 Data Through a Service Account, and What Comes Back

This version requires PHP 8.4 and Laravel 13, which shuts out older apps

The installation note is short and strict: this version requires PHP 8.4 or higher and Laravel 13. The package installs through Composer:

composer require spatie/laravel-analytics

Publishing the config file is optional:

php artisan vendor:publish --tag="analytics-config"

The published file lands in `config/analytics.php`. The consequence of the version line is practical. An application still on an older Laravel or a PHP release below 8.4 cannot take this release, and Composer will refuse the install. The repository has an UPGRADE.md file and a CHANGELOG.md for moving between major versions, and the project homepage points to a post announcing version 5 with support for GA4.

If you are stuck on an older stack, you cannot use this version at all, and you would need to stay on an earlier major release that matches your Laravel version. Check your platform before planning around the package, and read the upgrade notes if you are coming from version 4 or earlier, since the move to GA4 changed the underlying API the package talks to.

Everything depends on a Google service account JSON file you create by hand

The package does not collect data. It reads from Google, and to do that it needs credentials. The setup guide walks through the Google API console: select or create a project, search the API Library for Google Analytics Data API and enable it, then open Credentials and create a Service account key. You can name the account anything, and its service account ID is an email address you will need later.

On the service account's details screen, you pick keys, then Add key, then Create new key, choose JSON as the key type and download the file.

Save that JSON inside your Laravel project at the path in the `service_account_credentials_json` config key. The default in the published config is `storage_path('app/analytics/service-account-credentials.json')`. The config comment adds that you can pass the credentials as an array instead of a file path. The README says plainly that the file contains potentially sensitive information and recommends against committing it to your git repository.

The consequence is a secret that must be provisioned on every environment. Local, staging and production each need the file, or the array form fed from your secret store, and a missing file shows up as an error when the first call is made.

The service account must be added to the GA4 property as a user with the Analyst role

A credentials file alone returns nothing. The README assumes you already have an Analytics account and are using the new GA4 properties. First you need the property ID: in Analytics, go to Settings, then Property Settings, and copy it. That value goes into the `ANALYTICS_PROPERTY_ID` key of your `.env` file, which the config reads through `'property_id' => env('ANALYTICS_PROPERTY_ID')`.

Then you grant access. In the Admin section of the property, open Property Access Management and click the plus sign in the top right corner to add a user. Enter the email address from the `client_email` key of the downloaded JSON. The Analyst role is enough.

Two mistakes are common here, and both come from skipping a step. The guide assumes GA4 properties, so use a GA4 property ID. And forgetting to add the service account to the property leaves you with valid credentials that Google refuses to use for that property. Least privilege is built in: because only Analyst is needed, you do not hand the account edit rights, which is the safer setting to leave in place.

Period objects define the window, and custom ranges use Carbon dates

Every fetch method takes a `Period`. The README shows relative windows first:

use Spatie\Analytics\Facades\Analytics;
use Spatie\Analytics\Period;

//fetch the most visited pages for today and the past week
Analytics::fetchMostVisitedPages(Period::days(7));

//fetch visitors and page views for the past week
Analytics::fetchVisitorsAndPageViews(Period::days(7));

`Period::months(6)` covers the last six months, as in the second usage example. For finer control you pass a start and an end date to the period object:

$startDate = Carbon::now()->subYear();
$endDate = Carbon::now();

Period::create($startDate, $endDate);

The relative helpers are counted back from today, so a call with seven days includes the current day and may show partial data for it, a limit of how Google processes recent traffic. For reports that must be reproducible, use `Period::create` with fixed dates so a report run next week gives the same window.

Most methods return an `Illuminate\Support\Collection`, so everything you know about Laravel collections applies: map, sum, groupBy and so on, with no special result class to learn.

Return keys differ between methods, and one documented list repeats the date key

The provided methods share a pattern but not a shape, so check the keys before you rely on them. `fetchVisitorsAndPageViews(Period $period)` returns items with `activeUsers`, `screenPageViews` and `pageTitle`. `fetchVisitorsAndPageViewsByDate(Period $period)` adds a `date` key to those. `fetchTotalVisitorsAndPageViews(Period $period)` is documented as returning `date`, `date`, `visitors` and `pageViews`, with the date key listed twice, which looks like a typo in the docs.

The usage section of the README also describes `$analyticsData` as an array holding `date`, `visitors` and `pageViews`, while the method reference for the first function lists `activeUsers` and `screenPageViews`. These are different naming schemes inside one document: GA4 style names in one place, older names in another.

`fetchMostVisitedPages(Period $period, int $maxResults = 20)` returns `fullPageUrl`, `pageTitle` and `screenPageViews`, and `fetchTopReferrers(Period $period, int $maxResults = 20)` returns `screenPageViews` plus a referrer key. The default limit of 20 matters: a site with many pages gets only the top twenty unless you pass a larger number. Dump one result in a test before building a view around a key name.

Responses are cached for a configurable number of minutes, and zero turns caching off

The published config includes a cache setting described as the number of minutes Google API responses will be cached. The comment says that if you set it to zero, the responses will not be cached. Read the default minutes value in your published `config/analytics.php`.

The tradeoff is freshness against calls. Caching keeps a dashboard page fast and avoids hitting Google on every page load. With caching off, every request that renders an analytics widget makes a fresh API call, which is slower and can run into Google's usage limits on a busy admin page.

The flip side of caching is stale numbers. A visitor chart that was cached ten minutes ago will not reflect a traffic spike now, so for a live view you would lower the setting, and for a nightly report you can leave it high. Because the cache is applied to API responses by the package, you can put your own caching on top for aggregated results, but the README gives no guidance on that.

The package is read-only. It does not insert tracking scripts, record hits or store events; GA4 must already be collecting the data.

Version 5.8.0 arrived in October 2026 under the MIT license from a company that asks for postcards

The release list shows 5.8.0 on 2026-10-19, 5.7.2 on 2026-09-29 and 5.7.1 on 2026-04-28, with the last push on 2026-10-22. The package is MIT licensed, and the repository is not archived. A gap of five months between 5.7.1 and 5.7.2 and then a feature release three weeks later shows uneven spacing, so pin a minor version in composer.json and read the changelog on updates.

The maintainer is Spatie, which funds open source work through paid products. The README asks users to support them by buying one of those products, and also asks for a postcard from your hometown mentioning which of their packages you use, with all received postcards published on a virtual postcard wall. That is a request, not a condition of the license.

The README's Support us banner is an advertisement link, so ignore it when judging the technical content. What you rely on is the code, the UPGRADE.md notes and the test suite in the tests folder. Note the boundary: this package neither replaces Google Analytics nor draws charts, it only fetches the numbers for you to display.

Editorial conclusion

spatie/laravel-analytics is a good fit for a Laravel site that already runs GA4 and wants visitor numbers inside its own admin pages without writing Google API code. It is the wrong tool if you want analytics without Google, a ready-made dashboard, or support for older stacks, since this version needs PHP 8.4 and Laravel 13 and everything depends on a service account you must set up yourself.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spatie/laravel-analytics on GitHub