Laravel Metrics Ga4 Laravel Package

Technical Evaluation

Release reviewed: 1.0.0 (first public release). This establishes the baseline assessment.

Architecture fit

• Thin, read-only client for the GA4 Data API surfaced through a GA4 facade. No persistence layer beyond spatie/laravel-settings (credentials) and an access-token cache — this is the right shape for a Laravel integration and adds no runtime service to operate.
• Single global property configured via GA4_PROPERTY_ID. Any product need for per-tenant, per-brand, or per-environment property selection is not addressed and would require forking or wrapping.
• Facade-only access hides dependency injection and is awkward to stub. We should wrap it in an application-owned interface (adapter) so the package is a swappable detail rather than a hard dependency.

Integration feasibility

• Low effort: Composer install, publish/run the settings migration, provision a GCP service account with Viewer on the property, enable the Analytics Data API, seed GA4_PROPERTY_ID + GA4_SERVICE_ACCOUNT_JSON. Days for a spike, not weeks.
• Convenience methods (pages, sources, countries, browsers, devices, realtimeVisitors) cover most common dashboarding needs out of the box; runReport is the escape hatch for anything else.

Technical risk

• Credential blast radius. A long-lived service account private key moves from env into the database, encrypted with APP_KEY. Compromise or APP_KEY rotation is a meaningful operational hazard, and the key grants read access to every property the service account can see. Requires a dedicated, least-privilege service account scoped to one property.
• Metric semantic drift. Mapping visitors, visits, pageviews, bounce_rate, visit_duration invites Universal Analytics-era comparisons. GA4's bounce_rate is (1 − engagement rate), users ≠ sessions ≠ pageviews, and thresholds/sampling apply. Reporting built on these names risks being quietly wrong rather than visibly broken.
• Token cache in multi-node deployments. Cached access tokens require a shared cache store (Redis); otherwise each node re-signs JWTs. No documented behaviour on cache invalidation after key rotation.
• Quota behaviour is unproven. Typed RateLimitException exists, but there is no documented timeout, retry/backoff, throttling, or report-level caching. GA4 quotas are per-property, so every app instance and every user shares one budget.
• Synchronous HTTP in the request path by default — availability and latency of our features become coupled to Google's API unless we cache or precompute.
• Compatibility claim to verify. "Laravel 11, 12 or 13" implies forward support for an unreleased framework major; confirm the constraint actually resolves and CI covers each major, plus spatie/laravel-settings version compatibility.
• Undocumented return contract. Only exceptions are typed; return shapes (arrays vs. DTOs), pagination, row limits, and test fakes are unspecified. A 1.0.0 with no release history gives no signal on API stability.

Key questions

1. Multi-property / multi-tenant support, or is the property ID intentionally global?
2. Return types, pagination, and row-limit handling for large reports — arrays, DTOs, or raw GA4 responses?
3. Configurable timeouts, retries, and backoff — and is report caching built in or left to us?
4. Are data thresholding, sampling, and (not set) rows surfaced to callers, or silently returned?
5. Support for date ranges/comparisons, dimension filters, and custom metrics beyond the opinionated helpers?
6. Maintainer model, license, test coverage, CI matrix, and security disclosure policy — what is the bus factor?
7. Is Laravel 13 genuinely tested, and is the GA4 Data API version pinned?
8. Does the package log request payloads or credentials at any log level?

Integration Approach

Stack fit

• Matches modern Laravel (PHP 8.2+, Laravel 11–13); no new infrastructure beyond a shared cache store and a GCP project with the Analytics Data API enabled.
• Dependency chain is modest: spatie/laravel-settings, an HTTP client, and the OpenSSL extension for local JWT signing.
• Service account needs property-level Viewer only — confirm no account-level grants are used.

Migration path

• Greenfield integration (no incumbent recorded). If this replaces Universal Analytics reporting or a BI vendor's GA connector, run a parallel period and expect non-comparable numbers by design.
• Because the package is thin, the real migration work is metric redefinition for stakeholders, not code.

Compatibility

• PHP 8.2 baseline is acceptable for most estates; confirm against our minimum supported runtime.
• Requires a settings table migration — coordinate with release/rollback planning and confirm it is additive and reversible.
• Multi-node deployments must configure a shared cache store before enabling token caching.
• Encrypted settings depend on APP_KEY stability; a rotation runbook (decrypt → re-seed) is required.

Sequencing

1. GCP setup: dedicated service account, least privilege, non-production property.
2. Spike branch: install, publish migration, validate every facade method against the GA4 UI for a known date range.
3. Introduce our own adapter interface + property resolution config so the package can be replaced.
4. Add a caching/precompute layer and move report generation off the request path (queue/scheduler).
5. Wire into dashboards and product features.
6. Add observability (auth failures, rate-limit events, empty/thresholded responses), then promote to the production property.

Operational Impact

Maintenance

• Small surface area (HTTP client + credential plumbing) is a genuine advantage; the risk is project maturity, not complexity. Pin the version, watch releases, and assume we may need to fork — the adapter wrapper makes that cheap.
• Ongoing upkeep is dominated by external change: GA4 API evolution, spatie/laravel-settings majors, and Laravel major upgrades.

Support

• Typed exceptions are a real operational win; publish a runbook mapping AuthenticationException → key/permission/property misconfiguration, RateLimitException → backoff and quota review, GA4Exception → schema or request problem.
• Support burden will concentrate on "the numbers look wrong," not on crashes — invest in documented metric definitions.

Scaling

• Scales horizontally as a client; the binding constraint is GA4 quota per property (daily tokens, concurrent requests), not application capacity.
• Cache aggressively and precompute rollups. Avoid per-user realtimeVisitors polling — it burns quota in proportion to traffic and is the most likely source of self-inflicted rate limiting.

Failure modes

• Revoked or rotated service account key; expired credentials.
• Wrong or missing GA4_PROPERTY_ID, or Analytics Data API not enabled on the project.
• APP_KEY rotation breaking encrypted settings decryption.
• Shared cache outage forcing JWT re-signing on every request.
• Quota exhaustion, especially from realtime polling across multiple instances.
• Data thresholding/sampling producing silently incomplete result sets.
• GA4 response schema changes returning empty or shifted data rather than errors.
• Missing HTTP timeouts causing request pileup under degraded Google API conditions.
• Timezone/date-boundary off-by-one in reported ranges.

Ramp-up

• ~1 day for a Laravel developer to be productive; ~1 week for analytics/product to validate metric parity and agree definitions.
• The real onboarding cost is governance: a service account provisioning and secret rotation runbook, a documented metric glossary, and a named owner for the package and its quotas.