Laravel GA4

https://github.com/jeffersongoncalves/laravel-ga4
Admin
Laravel GA4 is a lightweight Google Analytics 4 API client for Laravel that wraps the GA4 Data API,...
Tokens:3,546
Snippets:37
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Laravel GA4 with Composer

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Installs the Laravel GA4 package via Composer.

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

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

### GA4Client Usage Examples

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Shows the main GA4Client static methods: runReport, runRealtimeReport, listConversionEvents, createConversionEvent, and sendEvent. Property IDs can be bare numeric or 'properties/...' format. sendEvent can override measurement ID and API secret per call.

```php
use JeffersonGoncalves\GA4\GA4Client;

// Run a report (property id can be a bare numeric id or "properties/123456789")
$report = GA4Client::runReport('123456789', ['country'], ['activeUsers'], '7daysAgo', 'today');

// Realtime report — no date range, always "now"
$realtime = GA4Client::runRealtimeReport('123456789', ['country'], ['activeUsers']);

// List the conversion events configured on a property
$events = GA4Client::listConversionEvents('123456789');

// Mark an existing event as a conversion
$event = GA4Client::createConversionEvent('123456789', 'purchase');

// Send a Measurement Protocol event (fire-and-forget)
$accepted = GA4Client::sendEvent('client-id-123', 'purchase', ['value' => 19.99, 'currency' => 'USD']);

// Override the configured measurement id / api secret per call
$accepted = GA4Client::sendEvent('client-id-123', 'purchase', [], 'G-OTHERSTREAM', 'other-secret');
```

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

### GA4Client Public API Usage Examples

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

Shows how to use the GA4Client for historical and realtime reports, conversion events, and sending events. The runReport method defaults to 30 days ago to today when no date range is provided. All methods return arrays or null, except sendEvent which returns a boolean.

```php
use JeffersonGoncalves\GA4\GA4Client;

// Data API — historical report, defaults to 30daysAgo -> today
GA4Client::runReport('123456789', ['country'], ['activeUsers'], '7daysAgo', 'today');
// array<string,mixed>|null

// Data API — realtime report, no date range
GA4Client::runRealtimeReport('123456789', ['country'], ['activeUsers']);
// array<string,mixed>|null

// Admin API — conversion events
GA4Client::listConversionEvents('123456789');              // list<array<string,mixed>>
GA4Client::createConversionEvent('123456789', 'purchase'); // array<string,mixed>|null

// Measurement Protocol — fire-and-forget event
GA4Client::sendEvent('client-id', 'purchase', ['value' => 19.99]); // bool
```

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

### GA4 Configuration File (config/ga4.php)

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Default configuration file for the package. Maps environment variables to configuration keys; timeout defaults to 8 seconds.

```php
// config/ga4.php
return [
    'access_token' => env('GA4_ACCESS_TOKEN'),
    'measurement_id' => env('GA4_MEASUREMENT_ID'),
    'api_secret' => env('GA4_API_SECRET'),
    'timeout' => (int) env('GA4_TIMEOUT', 8),
];
```

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

### Dev Commands for Testing, Static Analysis, and Formatting

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

Commands to run the test suite with Pest, static analysis with PHPStan level 5 + Larastan, and code formatting with Pint using the Laravel preset.

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

# Run static analysis (PHPStan level 5 + Larastan)
vendor/bin/phpstan analyse

# Format code (Pint, Laravel preset)
vendor/bin/pint
```

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

### Run Tests with Composer

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Runs the package test suite.

```bash
composer test
```

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

### Run Static Analysis with Composer

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Runs static analysis (PHPStan) on the codebase.

```bash
composer analyse
```

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

### Publish GA4 Configuration File

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Optionally publishes the package configuration file to the application's config directory.

```bash
php artisan vendor:publish --tag="ga4-config"
```

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

### Format Code with Composer

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Formats the codebase according to the project's code style rules.

```bash
composer format
```

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

### Configure the GA4 service provider

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

The service provider only registers the config file using spatie/laravel-package-tools. The package name is 'ga4'.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('ga4')
        ->hasConfigFile();
}
```

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

### sendEvent() Usage with Default and Overridden Credentials

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

Shows how to send events using the configured measurement_id and api_secret, or override them per call. If neither is provided, the call is skipped and returns false.

```php
// Uses the configured measurement_id / api_secret
GA4Client::sendEvent('client-id', 'purchase', ['value' => 19.99]);

// Overrides them per call
GA4Client::sendEvent('client-id', 'purchase', [], 'G-OTHERSTREAM', 'other-secret');
```

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

### GA4 namespace structure

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

Shows the namespace layout for the GA4 package, with GA4ServiceProvider and GA4Client classes.

```text
JeffersonGoncalves\GA4\
    GA4ServiceProvider     # Registers the config file only
    GA4Client               # Static Data API / Admin API / Measurement Protocol client
```

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

### Configure GA4 Environment Variables

Source: https://github.com/jeffersongoncalves/laravel-ga4/blob/main/README.md

Environment variables required for the GA4 client. GA4_ACCESS_TOKEN is the OAuth bearer token for Data/Admin APIs; GA4_MEASUREMENT_ID and GA4_API_SECRET identify the Measurement Protocol data stream; GA4_TIMEOUT sets the HTTP timeout in seconds.

```env
GA4_ACCESS_TOKEN=ya29.xxxxxxxxxxxxxxxxxxxx
GA4_MEASUREMENT_ID=G-XXXXXXX
GA4_API_SECRET=xxxxxxxxxxxxxxxxxxxxxx
GA4_TIMEOUT=8
```

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

### GA4 environment variables

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

Defines the required environment variables for the GA4 package: access token, measurement ID, API secret, and timeout.

```env
GA4_ACCESS_TOKEN=ya29.your-oauth-access-token
GA4_MEASUREMENT_ID=G-XXXXXXX
GA4_API_SECRET=your-measurement-protocol-api-secret
GA4_TIMEOUT=8
```

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

### Assert Measurement Protocol Event with Http::fake

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

Fakes the Measurement Protocol endpoint (www.google-analytics.com/mp/collect*) to return a 204 response. Asserts that sendEvent returns true.

```php
it('sends a measurement protocol event', function () {
    Http::fake([
        'www.google-analytics.com/mp/collect*' => Http::response('', 204),
    ]);

    expect(GA4Client::sendEvent('client-1', 'purchase'))->toBeTrue();
});
```

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

### normalizePropertyId() Method Implementation

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

Private static method that trims an optional 'properties/' prefix and validates that the remainder is purely numeric. Throws InvalidArgumentException for empty or non-numeric values.

```php
private static function normalizePropertyId(string $propertyId): string
{
    $propertyId = preg_replace('#^properties/#', '', $propertyId) ?? $propertyId;

    if ($propertyId === '' || preg_match('/^\d+$/', $propertyId) !== 1) {
        throw new InvalidArgumentException("Invalid GA4 property id: [{$propertyId}]. Expected a numeric id, optionally prefixed with 'properties/'.");
    }

    return $propertyId;
}
```

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

### Mock GA4 Report Response with Http::fake

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

Uses Laravel's Http facade to fake the analyticsdata.googleapis.com endpoint, returning a 200 response with an empty rows array. Asserts that runReport returns the decoded payload.

```php
use Illuminate\Support\Facades\Http;
use JeffersonGoncalves\GA4\GA4Client;

it('runs a report and returns the decoded payload', function () {
    Http::fake([
        'analyticsdata.googleapis.com/*' => Http::response(['rows' => []], 200),
    ]);

    expect(GA4Client::runReport('123456789'))->toBe(['rows' => []]);
});
```
Tokens:
Raw