Laravel Analytics

https://github.com/spatie/laravel-analytics
Admin
This package allows you to easily retrieve data from Google Analytics, providing methods to fetch...
Tokens:45,583
Snippets:346
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: Advanced manual construction

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

Building the client components individually, for example to swap the cache repository.

```php
use Spatie
ullAnalytics
ullAnalyticsClientFactory;

$googleService = AnalyticsClientFactory::createAuthenticatedGoogleClient([
    'service_account_credentials_json' => storage_path('app/analytics/service-account-credentials.json'),
]);

$client = AnalyticsClientFactory::createAnalyticsClient(
    [
        'cache_lifetime_in_minutes' => 60 * 24,
    ],
    $googleService,
);
```

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

### Install spatie/laravel-analytics via Composer

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Installs the package via Composer.

```bash
composer require spatie/laravel-analytics
```

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

### OrderBy example for get method

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Example of building an $orderBy array for the get method. It sorts by the 'date' dimension in descending order and by the 'pageViews' metric in ascending order.

```php
$orderBy = [
    OrderBy::dimension('date', true),
    OrderBy::metric('pageViews', false),
];
```

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

### Example: Standard usage

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The standard entry point used by the AnalyticsServiceProvider when booting.

```php
use Spatie
ullAnalytics
ullAnalyticsClientFactory;

$analyticsConfig = config('analytics');

// inside the service provider binding:
$client = AnalyticsClientFactory::createForConfig($analyticsConfig);
```

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

### Installing Analytics fake through the facade

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/fakes-analytics.md

Typical usage: install the fake via Analytics::fake($expected), then any analytics call returns the expected collection. Calling Analytics::fake() with no arguments swaps back to an empty collection.

```php
use Spatie\Analytics\Facades\Analytics;

$expected = collect([
    ['browser' => 'Chrome', 'screenPageViews' => 120],
    ['browser' => 'Firefox', 'screenPageViews' => 40],
]);

Analytics::fake($expected);

// any analytics call now returns $expected, e.g.:
$browsers = Analytics::fetchTopBrowsers(Period::days(7));
expect($browsers)->toEqual($expected);

// remember to swap the real implementation back
Analytics::fake(); // subsequent calls return an empty collection
```

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

### Facade Installation: Analytics::fake

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/fakes-analytics.md

Explains how the fake is installed via the facade to replace the real Analytics service, with a default result of an empty collection.

```APIDOC
## Facade Installation: Analytics::fake

### Description
Replaces the Analytics facade root with a fake instance that returns the provided result (or an empty collection if not provided) for any method call.

### Method
fake

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `result` | mixed | no | empty Collection | The value to return from all fake method calls |

### Example

```php
use Spatie\Analytics\Facades\Analytics;

$expected = collect([
    ['browser' => 'Chrome', 'screenPageViews' => 120],
]);

Analytics::fake($expected);

// any analytics call now returns $expected
$browsers = Analytics::fetchTopBrowsers(Period::days(7));

// reset to a new fake with an empty collection
Analytics::fake(); // subsequent calls return an empty collection
```
```

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

### Install Laravel Analytics via Composer and Publish Config

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/README.md

Run these commands to install the package and publish the configuration file to your Laravel project.

```bash
composer require spatie/laravel-analytics
php artisan vendor:publish --tag="analytics-config"
```

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

### Full custom configuration for config/analytics.php

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/configuration.md

Example configuration file for the package, including property ID, service account credentials, and cache settings.

```php
// config/analytics.php
return [
    'property_id' => env('ANALYTICS_PROPERTY_ID'),

    // path variant:
    'service_account_credentials_json' => storage_path('app/analytics/service-account-credentials.json'),
    // array variant:
    // 'service_account_credentials_json' => [
    //     'type' => 'service_account',
    //     'project_id' => '...',
    //     'client_email' => '...',
    //     ...
    // ],

    'cache_lifetime_in_minutes' => 30, // cache Google responses for 30 minutes

    'cache' => ['store' => 'file'], // template value; not read by this package's source
];
```

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

### Metric filter example using NumericFilter

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Example of creating a $metricFilter for the get method. It filters aggregated rows to include only those where the 'eventCount' metric is greater than 3, similar to a SQL HAVING clause.

```php
use Google\Analytics\Data\V1beta\Filter;
use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\Filter\NumericFilter;
use Google\Analytics\Data\V1beta\NumericValue;
use Google\Analytics\Data\V1beta\Filter\NumericFilter\Operation;

$metricFilter = new FilterExpression([
    'filter' => new Filter([
        'field_name' => 'eventCount',
        'numeric_filter' => new NumericFilter([
            'operation' => Operation::GREATER_THAN,
            'value' => new NumericValue([
                'int64_value' => 3,
            ]),
        ]),
    ]),    
]);
```

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

### Basic usage example with assertions

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/type-caster.md

Shows how to resolve the TypeCaster and use castValue for a date, an integer metric, and a string passthrough, with corresponding expectations.

```php
use Spatie\Analytics\TypeCaster;

$typeCaster = resolve(TypeCaster::class);

$date = $typeCaster->castValue('date', '20210101');          // Illuminate\Support\Carbon
$users = $typeCaster->castValue('activeUsers', '15');        // 15 (int)
$title = $typeCaster->castValue('pageTitle', 'Home');        // 'Home' (string passthrough)

expect($date)->toBeInstanceOf(Carbon::class);
expect($users)->toBeInt()->toBe(15);
expect($title)->toBeString()->toBe('Home');
```

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

### Dimension filter example using FilterExpression

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Example of creating a $dimensionFilter for the get method. It filters results to include only rows where the 'eventName' dimension exactly matches 'click'.

```php
use Google\Analytics\Data\V1beta\Filter;
use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\Filter\StringFilter;
use Google\Analytics\Data\V1beta\Filter\StringFilter\MatchType;

$dimensionFilter = new FilterExpression([
    'filter' => new Filter([
        'field_name' => 'eventName',
        'string_filter' => new StringFilter([
            'match_type' => MatchType::EXACT,
            'value' => 'click',
        ]),
    ]),    
]);
```

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

### Invalid configuration example

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-service-provider.md

Demonstrates that setting an empty property_id causes an InvalidConfiguration exception when the singleton is resolved.

```php
config()->set('analytics.property_id', '');
$analytics = $this->app['laravel-analytics']; // throws Spatie\Analytics\Exceptions\InvalidConfiguration::propertyIdNotSpecified
```

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

### setCacheLifeTimeInMinutes usage example

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

Example call that caches responses for 3600 seconds (60 minutes). A value of 0 disables caching.

```php
$client->setCacheLifeTimeInMinutes(60); // responses cached for 3600 seconds
```

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

### Fake Analytics facade in a Pest test

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Use Analytics::fake() to mock the package's facade in your own project tests. This example shows a Pest test that fakes the facade, performs a GET request to '/analytics', and asserts a 200 status.

```php
<?php

use Spatie\Analytics\Facades\Analytics;

test('feature in your project', function () {
    // Arrange
    Analytics::fake();

    // Act
    $response = $this->actingAs($admin)->get('/analytics');

    // Assert
    $response->assertStatus(200);
});
```

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

### Create a custom Period with start and end dates

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Creates a custom Period by passing a start and end date to Period::create. Use this when you need more control over the date range than the predefined day or month periods.

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

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

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

### Period::days factory

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Static factory for a period spanning a given number of days back from today. The end date is Carbon::today() and the start date is Carbon::today()->subDays($numberOfDays)->startOfDay(), so the start is floored to the start of the day.

```php
public static function days(int $numberOfDays): static
```

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

### Period Constructor

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Initializes a new Period instance with a start and end date. Throws an InvalidPeriod exception if the start date is after the end date.

```php
public function __construct(DateTimeInterface $startDate, DateTimeInterface $endDate)
```

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

### Period::__construct

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Constructor for the Period class. Initializes a period with a start and end date, throwing an exception if the start date is after the end date.

```APIDOC
## Constructor

### `__construct`

```php
public function __construct(DateTimeInterface $startDate, DateTimeInterface $endDate)
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `startDate` | `DateTimeInterface` | yes | — | Window start |
| `endDate` | `DateTimeInterface` | yes | — | Window end |

**Throws** `Spatie\Analytics\Exceptions\InvalidPeriod` — exactly when `$startDate > $endDate` (see [errors.md](../errors.md)). Assigns the promoted public properties. The factory methods route through this constructor, so an inverted window throws even from `Period::days(...)` if Carbon's `today()` behaves unexpectedly — in normal use this surfaces via `Period::create()`.
```

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

### Sorting a query by dimension and metric

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/order-by.md

Example of using OrderBy in an Analytics::get call to sort by date descending and screenPageViews ascending.

```php
use Spatie	esting
use Spatie\Analytics\OrderBy;
use Spatie\Analytics\Facades\Analytics;

$result = Analytics::get(
    period: Period::days(7),
    metrics: ['screenPageViews'],
    dimensions: ['pageTitle', 'date'],
    orderBy: [
        OrderBy::dimension('date', true), // most recent first
        OrderBy::metric('screenPageViews', false), // then lowest page views first
    ],
);
```

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

### Set and get property ID

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Demonstrates switching the property ID on an Analytics instance and retrieving it. setPropertyId returns the same instance for chaining.

```php
$analytics->setPropertyId('987654');
$analytics->getPropertyId(); // '987654'
```

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

### get request array

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

The request array built by the get method. It includes property, date_ranges, metrics, dimensions, limit, offset, order_bys, dimension_filter, keep_empty_rows, and metric_filter. This array is passed to runReport().

```php
[
    'property'         => "properties/{$propertyId}",
    'date_ranges'      => [$period->toDateRange()],
    'metrics'          => $this->getFormattedMetrics($metrics),
    'dimensions'       => $this->getFormattedDimensions($dimensions),
    'limit'            => $maxResults,
    'offset'           => $offset,
    'order_bys'        => $orderBy,
    'dimension_filter' => $dimensionFilter,
    'keep_empty_rows'  => $keepEmptyRows,
    'metric_filter'    => $metricFilter,
]
```

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

### get method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

Signature of the get method for running a report. Accepts property ID, period, metrics, dimensions, and optional parameters like maxResults, orderBy, offset, filters, and keepEmptyRows. Returns a Collection of row arrays.

```php
public function get(
    string $propertyId,
    Period $period,
    array $metrics,
    array $dimensions = [],
    int $maxResults = 10,
    array $orderBy = [],
    int $offset = 0,
    ?FilterExpression $dimensionFilter = null,
    bool $keepEmptyRows = false,
    ?FilterExpression $metricFilter = null,
): Collection {
```

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

### new Spatie\Analytics\Period(DateTimeInterface $startDate, DateTimeInterface $endDate)

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/configuration.md

Constructor for the Period value object. It takes a start and end date. The start date must not be after the end date, otherwise an InvalidPeriod exception is thrown.

```APIDOC
## Constructor: new Spatie\Analytics\Period(DateTimeInterface $startDate, DateTimeInterface $endDate)

### Description
Creates a new Period instance with the given start and end dates.

### Parameters
- **startDate** (DateTimeInterface) - Required - Window start; must not be after endDate (else InvalidPeriod)
- **endDate** (DateTimeInterface) - Required - Window end

### Example
```php
$period = new Period($startDate, $endDate);
```
```

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

### Asserting the produced object graph

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/order-by.md

Example of verifying the output of OrderBy::dimension using test assertions.

```php
use Google\Analytics\Data\V1beta\OrderBy as GoogleOrderBy;
use Spatie\Analytics\OrderBy;

$result = OrderBy::dimension('date', true);

expect(get_class($result))->toBe(GoogleOrderBy::class)
    ->and($result->getDimension()->getDimensionName())->toBe('date')
    ->and($result->getDesc())->toBeTrue();
```

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

### Fake Analytics facade with expected results

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Specify expected results for the fake by passing an array or Illuminate\Support\Collection to Analytics::fake(). The example provides an array with pageTitle, activeUsers, and screenPageViews values, then asserts a 200 status on the '/analytics' route.

```php
<?php

use Spatie\Analytics\Facades\Analytics;

test('feature in your project', function () {
    // Arrange
    Analytics::fake([
        [
            'pageTitle' => 'Test Page',
            'activeUsers' => 10,
            'screenPageViews' => 20,
        ],
    ]);

    // Act
    $response = $this->actingAs($admin)->get('/analytics');

    // Assert
    $response->assertStatus(200);
});
```

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

### Period::create

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Creates a Period instance with a custom start and end date. The constructor validates the ordering of the dates.

```APIDOC
## Period::create

### Description
Creates a Period instance with a custom start and end date. The constructor validates the ordering of the dates.

### Method
`public static function create(DateTimeInterface $startDate, DateTimeInterface $endDate): self`

### Parameters
- `startDate` (DateTimeInterface) - Required - Window start
- `endDate` (DateTimeInterface) - Required - Window end

### Returns
Returns a new static instance with the given start and end dates.
```

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

### getRealtime

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Runs a generic query against the Google Analytics Realtime API. It has the same parameter surface as `get` but uses `minute_ranges` instead of `date_ranges`. Note that the underlying client does not forward `offset` or `keep_empty_rows`.

```APIDOC
## getRealtime

### Description
Runs a generic query against the Google Analytics Realtime API. It has the same parameter surface as `get` but uses `minute_ranges` instead of `date_ranges`. Note that the underlying client does not forward `offset` or `keep_empty_rows`.

### Method
`getRealtime`

### Signature
```php
public function getRealtime(
    Period $period,
    array $metrics,
    array $dimensions = [],
    int $maxResults = 10,
    array $orderBy = [],
    int $offset = 0,
    ?FilterExpression $dimensionFilter = null,
    bool $keepEmptyRows = false,
    ?FilterExpression $metricFilter = null,
): Collection
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `period` | `Period` | yes | — | Reporting window |
| `metrics` | `array` | yes | — | Metric API names to retrieve |
| `dimensions` | `array` | no | `[]` | Dimension names to group by |
| `maxResults` | `int` | no | `10` | Maximum number of rows |
| `orderBy` | `array` | no | `[]` | `Google\Analytics\Data\V1beta\OrderBy` objects (use `OrderBy::dimension()`/`OrderBy::metric()`) |
| `offset` | `int` | no | `0` | Row offset (pagination with `maxResults`) |
| `dimensionFilter` | `?FilterExpression` | no | `null` | Pre-aggregation dimension filter (`Google\Analytics\Data\V1beta\FilterExpression`) |
| `keepEmptyRows` | `bool` | no | `false` | If false, rows where all metrics are 0 are omitted; if true they are returned unless removed by a filter |
| `metricFilter` | `?FilterExpression` | no | `null` | Post-aggregation (HAVING-style) metric filter; dimensions cannot be used in it |

### Returns
Returns a `Collection` of row arrays keyed by the requested dimension/metric names.

### Notes
Delegates positionally to `$this->client->getRealtime(...)` (`src/Analytics.php:233–256`). Caveat: the underlying client's realtime request array does **not** forward `offset` or `keep_empty_rows` (see [AnalyticsClient](analytics-client.md)).
```

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

### Catching InvalidConfiguration exception

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/exceptions.md

Example of catching an InvalidConfiguration exception when fetching analytics data. The exception is thrown when the configuration is invalid, and the message can be retrieved via getMessage().

```php
use Spatie\Analytics\Facades\Analytics;
use Spatie\Analytics\Exceptions\InvalidConfiguration;

try {
    $result = Analytics::fetchVisitorsAndPageViews(Period::days(7));
} catch (InvalidConfiguration $e) {
    // $e->getMessage() is one of the two messages above
    report($e->getMessage());
}
```

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

### get

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Runs a generic report query against the Google Analytics Data API (GA4). It accepts a reporting period, metrics, dimensions, and various optional parameters for ordering, pagination, and filtering, returning a collection of row arrays.

```APIDOC
## get

### Description
Runs a generic report query against the Google Analytics Data API (GA4). It accepts a reporting period, metrics, dimensions, and various optional parameters for ordering, pagination, and filtering, returning a collection of row arrays.

### Method
`get`

### Signature
```php
public function get(
    Period $period,
    array $metrics,
    array $dimensions = [],
    int $maxResults = 10,
    array $orderBy = [],
    int $offset = 0,
    ?FilterExpression $dimensionFilter = null,
    bool $keepEmptyRows = false,
    ?FilterExpression $metricFilter = null,
): Collection
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `period` | `Period` | yes | — | Reporting window |
| `metrics` | `array` | yes | — | Metric API names to retrieve |
| `dimensions` | `array` | no | `[]` | Dimension names to group by |
| `maxResults` | `int` | no | `10` | Maximum number of rows |
| `orderBy` | `array` | no | `[]` | `Google\Analytics\Data\V1beta\OrderBy` objects (use `OrderBy::dimension()`/`OrderBy::metric()`) |
| `offset` | `int` | no | `0` | Row offset (pagination with `maxResults`) |
| `dimensionFilter` | `?FilterExpression` | no | `null` | Pre-aggregation dimension filter (`Google\Analytics\Data\V1beta\FilterExpression`) |
| `keepEmptyRows` | `bool` | no | `false` | If false, rows where all metrics are 0 are omitted; if true they are returned unless removed by a filter |
| `metricFilter` | `?FilterExpression` | no | `null` | Post-aggregation (HAVING-style) metric filter; dimensions cannot be used in it |

### Returns
Returns a `Collection` of row arrays keyed by the requested dimension/metric names.

### Notes
Delegates positionally to `$this->client->get($this->propertyId, $period, $metrics, $dimensions, $maxResults, $orderBy, $offset, $dimensionFilter, $keepEmptyRows, $metricFilter)` (`src/Analytics.php:208–231`).
```

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

### Instantiate Analytics with client and property ID

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Shows how to create an Analytics instance directly with an injected client and a property ID string.

```php
use Spatie\Analytics\Analytics;
use Spatie\Analytics\AnalyticsClient;

$analytics = new Analytics($client, '1234567');
```

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

### Catching InvalidPeriod exception

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/exceptions.md

Example of catching an InvalidPeriod exception when creating a period with an invalid date range. The exception is thrown when the start date is after the end date.

```php
use Spatie\Analytics\Period;
use Spatie\Analytics\Exceptions\InvalidPeriod;

try {
    $period = Period::create($endDate, $startDate); // startDate > endDate
} catch (InvalidPeriod $e) {
    // "Start date `...` cannot be after end date `...`."
    $period = Period::days(7);
}
```

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

### bootingPackage method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-service-provider.md

Declares the bootingPackage method that is called at package boot.

```php
public function bootingPackage()
```

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

### Access container bindings

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-service-provider.md

Shows how to resolve the 'laravel-analytics' singleton and the AnalyticsClient from the container after booting.

```php
$analytics = $this->app['laravel-analytics'];             // Spatie\Analytics\Analytics singleton
$client    = $this->app[AnalyticsClient::class];          // resolved from config on demand
```

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

### Period::years

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Creates a Period spanning the given number of years back from today, with the start floored to the start of the day.

```APIDOC
## Period::years

### Description
Creates a Period spanning the given number of years back from today, with the start floored to the start of the day.

### Method
`public static function years(int $numberOfYears): static`

### Parameters
- `numberOfYears` (int) - Required - How many years back the window spans

### Returns
Returns a Period with endDate set to today and startDate set to today minus the number of years, floored to the start of the day.
```

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

### Module graph of AnalyticsServiceProvider and AnalyticsClient

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/README.md

ASCII diagram showing the package's internal classes, their bindings, and helper methods. Use it as a quick reference for how AnalyticsServiceProvider registers the client and singleton, and how AnalyticsClient delegates to Google's runReport and runRealtimeReport.

```text
AnalyticsServiceProvider (package bootstrapping)
 ├─ registers AnalyticsClient binding  ← AnalyticsClientFactory::createForConfig(config('analytics'))
 │    ├─ createAuthenticatedGoogleClient() → Google BetaAnalyticsDataClient
 │    └─ createAnalyticsClient() → new AnalyticsClient(service, app(Repository::class)) + cache lifetime
 ├─ registers 'laravel-analytics' singleton → new Analytics(client, config['property_id'])
 └─ guardAgainstInvalidConfiguration() → throws InvalidConfiguration

Analytics (Spatie\Analytics\Analytics)
 └─ facade proxy: Spatie\Analytics\Facades\Analytics (accessor 'laravel-analytics', mixin of Analytics)
      └─ test stand-in: Spatie\Analytics\Fakes\Analytics
 └─ convenience fetchers call self::get() / self::getRealtime()

AnalyticsClient (talks to Google)
 ├─ get()          → runReport([...])            → Collection (row casts via TypeCaster)
 ├─ getRealtime()  → runRealtimeReport([...])    → Collection
 ├─ runReport() / runRealtimeReport() → cache remember/forget around serialized protobuf
 └─ helpers: determineCacheName(), getFormattedMetrics(), getFormattedDimensions()

Period → toDateRange()/toMinuteRange() → Google DateRange / MinuteRange
OrderBy → dimension()/metric() → Google OrderBy
TypeCaster::castValue() → Carbon / int / string
```

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

### Period::months

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Creates a Period spanning the given number of months back from today, with the start floored to the start of the day.

```APIDOC
## Period::months

### Description
Creates a Period spanning the given number of months back from today, with the start floored to the start of the day.

### Method
`public static function months(int $numberOfMonths): static`

### Parameters
- `numberOfMonths` (int) - Required - How many months back the window spans

### Returns
Returns a Period with endDate set to today and startDate set to today minus the number of months, floored to the start of the day.
```

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

### fetchTopOperatingSystems method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Method signature for fetching top operating systems. Returns a Collection where each item has keys 'screenPageViews' and 'operatingSystem'. The default maximum number of results is 10.

```php
public function fetchTopOperatingSystems(Period $period, int $maxResults = 10): Collection
```

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

### Period::days

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Creates a Period spanning the given number of days back from today, with the start floored to the start of the day.

```APIDOC
## Period::days

### Description
Creates a Period spanning the given number of days back from today, with the start floored to the start of the day.

### Method
`public static function days(int $numberOfDays): static`

### Parameters
- `numberOfDays` (int) - Required - How many days back the window spans

### Returns
Returns a Period with endDate set to today and startDate set to today minus the number of days, floored to the start of the day.
```

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

### configurePackage method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-service-provider.md

Declares the configurePackage method that receives a Package object and returns void.

```php
public function configurePackage(Package $package): void
```

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

### Direct instantiation of Analytics fake

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/fakes-analytics.md

Creates a fake instance with a collection of analytics data. Calling fetchVisitorsAndPageViews returns the configured collection.

```php
use Spatie\Analytics\Fakes\Analytics;
use Spatie\Analytics\Period;

$fake = new Analytics(collect([
    ['pageTitle' => 'Test Page', 'activeUsers' => 10, 'screenPageViews' => 20],
]));

$result = $fake->fetchVisitorsAndPageViews(Period::days(7)); // returns the configured collection
```

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

### createForConfig implementation

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The internal implementation of the createForConfig method.

```php
$authenticatedClient = self::createAuthenticatedGoogleClient($analyticsConfig);

return self::createAnalyticsClient($analyticsConfig, $authenticatedClient);
```

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

### Period constructor check for start date after end date

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/errors.md

Throws InvalidPeriod::startDateCannotBeAfterEndDate when the start date is strictly after the end date. Equal dates are permitted.

```php
if ($startDate > $endDate) {
    throw InvalidPeriod::startDateCannotBeAfterEndDate($startDate, $endDate);
}
```

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

### get method signature for custom Analytics queries

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Signature of the get method for all other Google Analytics queries. Use this method to run custom reports with metrics, dimensions, ordering, pagination, and filters.

```php
public function get(Period $period, array $metrics, array $dimensions = [], int $maxResults = 10, array $orderBy = [], int $offset = 0, ?FilterExpression $dimensionFilter = null, bool $keepEmptyRows = false, ?FilterExpression $metricFilter = null): Collection
```

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

### Run package tests with vendor/bin/pest

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Run the package's test suite using Pest. Execute this command from the project root.

```bash
vendor/bin/pest
```

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

### fetchTopOperatingSystems(Period $period, int $maxResults = 10, int $offset = 0): Collection

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/facade-analytics.md

Fetches the top operating systems used by visitors for the given period.

```APIDOC
## fetchTopOperatingSystems(Period $period, int $maxResults = 10, int $offset = 0): Collection

### Description
Fetches the top operating systems used by visitors for the given period.

### Method
fetchTopOperatingSystems

### Parameters
- **$period** (Period) - Required - The period for which to fetch data.
- **$maxResults** (int) - Optional - Maximum number of results to return. Default: 10.
- **$offset** (int) - Optional - Offset for pagination. Default: 0.

### Returns
- **Collection** - A collection of top operating systems data.
```

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

### Spatie\Analytics\Exceptions\InvalidPeriod::startDateCannotBeAfterEndDate

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/exceptions.md

Static factory method that returns a new InvalidPeriod instance with a message indicating that the start date cannot be after the end date. This is triggered when a Period is created with a start date later than the end date.

```APIDOC
## `Spatie\Analytics\Exceptions\InvalidPeriod::startDateCannotBeAfterEndDate`

### Description
Returns a new instance of `InvalidPeriod` with a pre-filled message indicating that the start date cannot be after the end date. This exception is triggered when a `Period` is constructed with a start date that is later than the end date.

### Method
`public static function startDateCannotBeAfterEndDate(DateTimeInterface $startDate, DateTimeInterface $endDate): static`

### Parameters
- **`startDate`** (DateTimeInterface) - Required - The offending start date.
- **`endDate`** (DateTimeInterface) - Required - The offending end date.

### Returns
- **Type:** `static` (instance of `InvalidPeriod`)
- **Message:** `Start date \`{$startDate->format('Y-m-d')}\` cannot be after end date \`{$endDate->format('Y-m-d')}\`.`

### Trigger
Triggered by the `Period` constructor when `$startDate > $endDate`.
```

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

### fetchTopOperatingSystems

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Fetches the top operating systems by screen page views for a given period. Returns a collection of rows with operating system name and screenPageViews count.

```APIDOC
## fetchTopOperatingSystems

### Description
Fetches the top operating systems by screen page views for a given period.

### Method
PHP method

### Signature
`public function fetchTopOperatingSystems(Period $period, int $maxResults = 10, int $offset = 0): Collection`

### Parameters
- **period** (Period) - Required - Reporting window
- **maxResults** (int) - Optional (default: 10) - Maximum number of rows
- **offset** (int) - Optional (default: 0) - Row offset (pagination)

### Return Value
Collection of rows with shape: `{ operatingSystem: string, screenPageViews: int }`

### Implementation Details
Delegates to `get()` with metrics: `['screenPageViews']`, dimensions: `['operatingSystem']`, orderBy: `[OrderBy::metric('screenPageViews', true)]`.
```

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

### createForConfig method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The method signature for creating an AnalyticsClient from the configuration array.

```php
public static function createForConfig(array $analyticsConfig): AnalyticsClient
```

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

### createAuthenticatedGoogleClient implementation

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The internal implementation of the createAuthenticatedGoogleClient method.

```php
return new BetaAnalyticsDataClient([
    'credentials' => $config['service_account_credentials_json'],
]);
```

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

### Constructor: __construct

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/fakes-analytics.md

Instantiates a new fake Analytics instance with a fixed result that will be returned by every method call.

```APIDOC
## Constructor: __construct

### Description
Creates a new fake Analytics instance that returns the given result for any method called on it.

### Method
__construct

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `result` | `mixed` | yes | — | The value to return for every intercepted method call |

### Example

```php
$fake = new Analytics(collect([
    ['pageTitle' => 'Test Page', 'activeUsers' => 10, 'screenPageViews' => 20],
]));
```
```

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

### fetchTotalVisitorsAndPageViews method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Method signature for fetching total visitors and page views. Returns a Collection where each item has keys 'date', 'date', 'visitors', and 'pageViews'.

```php
public function fetchTotalVisitorsAndPageViews(Period $period): Collection
```

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

### createForConfig

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

Creates a fully configured AnalyticsClient from the analytics config array. This is the main entry point used by the service provider.

```APIDOC
## createForConfig

### Description
Creates a fully configured AnalyticsClient with cache lifetime applied. This method is invoked by the service provider when the container binding for AnalyticsClient::class is resolved.

### Method
Static method

### Signature
public static function createForConfig(array $analyticsConfig): AnalyticsClient

### Parameters
- **analyticsConfig** (array) - Required - The resolved config('analytics') array.

### Returns
- **AnalyticsClient** - A fully configured AnalyticsClient instance.

### Implementation
```php
$authenticatedClient = self::createAuthenticatedGoogleClient($analyticsConfig);
return self::createAnalyticsClient($analyticsConfig, $authenticatedClient);
```

### Example
```php
use Spatie\Analytics\AnalyticsClientFactory;

$analyticsConfig = config('analytics');
$client = AnalyticsClientFactory::createForConfig($analyticsConfig);
```
```

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

### getPropertyId(): string

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/facade-analytics.md

Gets the currently set Google Analytics property ID.

```APIDOC
## getPropertyId(): string

### Description
Gets the currently set Google Analytics property ID.

### Method
getPropertyId

### Returns
- **string** - The current property ID.
```

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

### Fetch visitors and page views with Period::days and Period::months

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Shows how to use the Analytics facade to fetch visitors and page views for a period of days or months. The result is an Illuminate\Support\Collection where each item contains keys 'date', 'visitors', and 'pageViews'.

```php
use Spatie\Analytics\Facades\Analytics;

//retrieve visitors and page view data for the current day and the last seven days
$analyticsData = Analytics::fetchVisitorsAndPageViews(Period::days(7));

//retrieve visitors and page views since the 6 months ago
$analyticsData = Analytics::fetchVisitorsAndPageViews(Period::months(6));
```

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

### Analytics class constructor with promoted properties

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Defines the constructor that accepts an AnalyticsClient and a GA4 property ID, promoting them to protected properties. Used by the service provider or directly with a mock client.

```php
public function __construct(
    protected AnalyticsClient $client,
    protected string $propertyId,
) {}
```

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

### Handle invalid period exceptions

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

The Period class throws an InvalidPeriod exception if the start date is after the end date.

```php
use Spatie\Analytics\Period;
use Spatie\Analytics\Exceptions\InvalidPeriod;

$inverted = Period::create(Carbon::now(), Carbon::now()->subDay());

\/\/ caught as:
try {
    Period::create(Carbon::now(), Carbon::now()->subDay());
} catch (InvalidPeriod) {
    \/\/ "Start date `...` cannot be after end date `...`." — message from InvalidPeriod
    $period = Period::days(7);
}
```

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

### Constructor: __construct

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Initializes the Analytics class with a low-level AnalyticsClient and a GA4 property ID. User code can instantiate it directly or via the service container.

```APIDOC
## Constructor: __construct

### Description
Initializes the Analytics instance with a client and property ID. The client is used for all requests and the property ID is prefixed as `properties/{propertyId}`.

### Method
__construct

### Signature
```php
public function __construct(
    protected AnalyticsClient $client,
    protected string $propertyId,
) {}
```

### Parameters
- **client** (AnalyticsClient) - Required - Low-level client used to execute every request; created by AnalyticsClientFactory and bound in the container.
- **propertyId** (string) - Required - GA4 property ID, prefix added as `properties/{propertyId}` on every request.

### Example
```php
use Spatie\Analytics\Analytics;
use Spatie\Analytics\AnalyticsClient;

$analytics = new Analytics($client, '1234567');
```
```

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

### Handle analytics exceptions

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics.md

Shows how to catch InvalidPeriod and InvalidConfiguration exceptions during data retrieval or package initialization.

```php
use Spatie\Analytics\Period;
use Spatie\Analytics\Exceptions\InvalidPeriod;
use Spatie\Analytics\Exceptions\InvalidConfiguration;
use Spatie\Analytics\Facades\Analytics;

try {
    $period = Period::create(Carbon::now(), Carbon::now()->subDay()); // start > end
    Analytics::fetchTotalVisitorsAndPageViews($period);
} catch (InvalidPeriod) {
    // fall back to a valid window
    $period = Period::days(7);
    $result = Analytics::fetchTotalVisitorsAndPageViews($period);
} catch (InvalidConfiguration) {
    // e.g. property_id empty or credentials file missing
    report('analytics not configured', $result = collect());
}
```

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

### fetchVisitorsAndPageViews method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Method signature for fetching visitors and page views. Returns a Collection where each item has keys 'activeUsers', 'screenPageViews', and 'pageTitle'.

```php
public function fetchVisitorsAndPageViews(Period $period): Collection
```

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

### Period::toDateRange

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Converts the period to a Google Analytics DateRange object. Returns a DateRange with start and end dates formatted as Y-m-d.

```APIDOC
## `toDateRange`

```php
public function toDateRange(): DateRange
```

No parameters. Implementation (`src/Period.php:63–68`):

```php
return (new DateRange)
    ->setStartDate($this->startDate->format('Y-m-d'))
    ->setEndDate($this->endDate->format('Y-m-d'));
```

Returns `Google\Analytics\Data\V1beta\DateRange` with both dates formatted `Y-m-d`. Used by `AnalyticsClient::get()` (`date_ranges`).
```

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

### createAnalyticsClient implementation

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The internal implementation of the createAnalyticsClient method.

```php
$client = new AnalyticsClient($googleService, app(Repository::class));
$client->setCacheLifeTimeInMinutes($analyticsConfig['cache_lifetime_in_minutes']);
return $client;
```

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

### fake

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/facade-analytics.md

Swaps the facade root with a fake instance for testing. When called, all subsequent mixed-in method calls return the provided result or an empty collection by default.

```APIDOC
## fake

### Description
Swaps the facade root with a fake instance for testing. When called, all subsequent mixed-in method calls return the provided result or an empty collection by default.

### Method
public static function fake(mixed $result = null)

### Parameters
- **result** (mixed) - Optional - The value every subsequent mixed-in method call returns while faking. Defaults to null, which results in an empty collection.

### Return Value
- **mixed** - The result of the facade swap (library-managed).
```

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

### Fetch visitors and top pages with Analytics facade

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/facade-analytics.md

Basic production usage: fetch visitors and page views for the last 7 days and most visited pages for the last month with a max of 25 results.

```php
use Spatie\Analytics\Facades\Analytics;
use Spatie\Analytics\Period;

$visitors = Analytics::fetchVisitorsAndPageViews(Period::days(7));
$topPages = Analytics::fetchMostVisitedPages(Period::months(1), maxResults: 25);
```

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

### AnalyticsClient basic report execution

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

Instantiates the AnalyticsClient and retrieves a report for a specific property and period.

```php
use Spatie\Analytics\AnalyticsClient;
use Spatie\
Analytics\Period;

$client = new AnalyticsClient($googleService, app(Repository::class));
$client->setCacheLifeTimeInMinutes(60);

$rows = $client->get(
    propertyId: '1234567',
    period: Period::days(7),
    metrics: ['activeUsers'],
    dimensions: ['date'],
    maxResults: 30,
);
```

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

### fetchVisitorsAndPageViewsByDate method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Method signature for fetching visitors and page views grouped by date. Returns a Collection where each item has keys 'date', 'activeUsers', 'screenPageViews', and 'pageTitle'.

```php
public function fetchVisitorsAndPageViewsByDate(Period $period): Collection
```

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

### createAuthenticatedGoogleClient method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

The method signature for creating the authenticated Google BetaAnalyticsDataClient.

```php
public static function createAuthenticatedGoogleClient(array $config): BetaAnalyticsDataClient
```

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

### Create explicit periods using Carbon

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Define custom start and end dates using Carbon instances to create a Period object for analytics requests.

```php
use Carbon\Carbon;
use Spatie\Analytics\Period;
use Spatie\Analytics\Facades\Analytics;

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

$period = Period::create($startDate, $endDate);
$result = Analytics::fetchMostVisitedPages($period, maxResults: 50);
```

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

### Period::toMinuteRange

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Converts the period to a Google Analytics MinuteRange object. Returns a MinuteRange with start and end minutes ago values derived from the period dates.

```APIDOC
## `toMinuteRange`

```php
public function toMinuteRange(): MinuteRange
```

No parameters. Implementation (`src/Period.php:70–75`):

```php
return (new MinuteRange)
    ->setStartMinutesAgo($this->endDate->diff($this->startDate)->i)
    ->setEndMinutesAgo($this->endDate->format('i'));
```

Returns `Google\Analytics\Data\V1beta\MinuteRange` used by `AnalyticsClient::getRealtime()` (`minute_ranges`): `startMinutesAgo` is the difference between `endDate` and `startDate` (accessed through Carbon's `diff(...)->i`), `endMinutesAgo` is `endDate` formatted with Carbon's `i` token. The exact numeric meaning of the `i` accessor/format token is defined by the `nesbot/carbon` dependency and is not expanded in this repository — verify against the installed Carbon version before relying on realtime minute precision.
```

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

### Register provider in Testbench

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-service-provider.md

Shows how to register the AnalyticsServiceProvider in a test class extending Orchestra\Testbench\TestCase.

```php
use Spatie\Analytics\AnalyticsServiceProvider;

// in a class extending Orchestra\Testbench\TestCase
protected function getPackageProviders($app)
{
    return [AnalyticsServiceProvider::class];
}
```

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

### Period public properties

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/period.md

Public properties of the Period value object. They define the start and end of the date window. The types are DateTimeInterface, so Carbon and DateTimeImmutable instances are accepted.

```php
public DateTimeInterface $startDate;

public DateTimeInterface $endDate;
```

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

### fetchTopBrowsers method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/README.md

Method signature for fetching top browsers. Returns a Collection where each item has keys 'screenPageViews' and 'browser'. The default maximum number of results is 10.

```php
public function fetchTopBrowsers(Period $period, int $maxResults = 10): Collection
```

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

### createAuthenticatedGoogleClient

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client-factory.md

Creates an authenticated BetaAnalyticsDataClient using the service account credentials from the config.

```APIDOC
## createAuthenticatedGoogleClient

### Description
Creates an authenticated Google Analytics Data client using the service account credentials JSON from the config. The credentials can be a file path or an inline array.

### Method
Static method

### Signature
public static function createAuthenticatedGoogleClient(array $config): BetaAnalyticsDataClient

### Parameters
- **config** (array) - Required - Analytics config array.

### Returns
- **BetaAnalyticsDataClient** - Authenticated Google Analytics Data client.

### Implementation
```php
return new BetaAnalyticsDataClient([
    'credentials' => $config['service_account_credentials_json'],
]);
```

### Example
```php
use Spatie\Analytics\AnalyticsClientFactory;

$googleService = AnalyticsClientFactory::createAuthenticatedGoogleClient([
    'service_account_credentials_json' => storage_path('app/analytics/service-account-credentials.json'),
]);
```
```

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

### AnalyticsClient constructor

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

Constructor that accepts an authenticated BetaAnalyticsDataClient and a cache repository. The cache is used to memoize serialized report responses.

```php
public function __construct(
    protected BetaAnalyticsDataClient $service,
    protected Repository $cache,
) {}
```

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

### getRealtime method signature

Source: https://github.com/spatie/laravel-analytics/blob/main/_autodocs/api-reference/analytics-client.md

Signature of the getRealtime method for realtime reporting. Accepts the same parameters as get, but uses minute_ranges and calls runRealtimeReport(). Note that offset and keep_empty_rows are accepted but not sent to Google.

```php
public function getRealtime(
    string $propertyId,
    Period $period,
    array $metrics,
    array $dimensions = [],
    int $maxResults = 10,
    array $orderBy = [],
    int $offset = 0,
    ?FilterExpression $dimensionFilter = null,
    bool $keepEmptyRows = false,
    ?FilterExpression $metricFilter = null,
): Collection {
```
Tokens:
Raw