Laravel Google Analytics Laravel Package

Getting Started

• Install with composer require akki-io/laravel-google-analytics. v12.0 targets Laravel 12, so confirm your app is on Laravel 12 and the PHP version required by that Laravel release.
• Publish the package config with php artisan vendor:publish and select the Google Analytics package config.
• Create a Google Cloud service account, enable the Google Analytics Data API, download the JSON credentials, and point the package config/env at that file.
• Set the GA4 property ID in config/env. Use the numeric GA4 property ID, not a G-... measurement ID.
• Add the service account email as a viewer on the GA4 property.
• First useful call: fetch the last 30 days of active users by date through the package facade, cache the result, and render it in a dashboard or scheduled report.

Implementation Patterns

• Wrap package calls in an application service or repository instead of calling the facade directly from controllers. Return plain arrays/DTOs so views and API responses are not coupled to Google response objects.
• Use the package for server-side reporting: dashboards, scheduled summaries, admin metrics, and internal analytics. Do not use it as a replacement for client-side GA4 pageview tracking.
• Cache report responses by property ID, date range, metrics, dimensions, and filters. GA4 Data API quotas and latency make per-request uncached calls a poor default.
• Keep realtime reporting separate from historical reporting. Use realtime calls sparingly and with short cache TTLs.
• For recurring reports, run an artisan command on a schedule, fetch the report once, and persist the normalized rows locally.
• Validate metric/dimension combinations against GA4’s schema before shipping. Keep a small set of known-good report definitions rather than accepting arbitrary user input.
• In tests, bind a fake implementation or mock the facade. Do not hit the real Google Analytics API in the test suite.
• For multi-tenant or multi-property apps, resolve the property ID per tenant and keep credentials/property selection explicit in your own config layer.

Gotchas and Tips

• v12.0 is primarily a Laravel 12 compatibility release. There are no new reporting features called out; treat it as a dependency/compatibility update and re-run your analytics integration tests after upgrading.
• After upgrading, clear cached config (php artisan config:clear) and verify composer constraints. Version numbers in this package track Laravel major support, so do not assume v12.0 implies a new GA4 API surface.
• GA4 property IDs are numeric. A measurement ID (G-...) will not work for the Data API.
• The service account must be granted access inside GA4 itself, not only in Google Cloud. Missing property access is a common source of permission errors.
• Credentials paths can break under config caching or deployment. Prefer an absolute path or a path resolved through base_path()/env, and verify the file exists in the deployed environment.
• GA4 metrics and dimensions are not freely composable. Unsupported combinations return API errors; test each report definition explicitly.
• Date handling and timezone can differ from your app timezone. GA4 reporting uses the property’s timezone settings, so “today” may not match your application’s “today.”
• Response objects from the Google client can be verbose. Normalize them immediately at the boundary of your service layer.
• Cache aggressively for dashboards, but avoid caching realtime data for long periods. Use separate cache keys and TTLs for historical versus realtime reports.
• If you need custom behavior, wrap the package behind your own interface and swap implementations in the container. That keeps future package upgrades from leaking into controllers and views.