Laravel Metrics Posthog Laravel Package

Product Decisions This Supports

• Embedding product analytics in your own product surface. The facade exposes aggregate, timeseries, breakdown, pages, sources, countries, browsers, devices and realtimeVisitors as first-class methods, which maps directly to the common dashboard widgets a PM would spec (traffic trend, top pages, acquisition mix, live activity). That makes "build an in-app analytics tab" a plausible roadmap item instead of a PostHog-UI-only dependency.
• Build vs. buy on the reporting layer. The alternative is hand-rolling a HogQL HTTP client plus response parsing plus error handling. This package is a thin, typed wrapper — worth buying (adopting) if your reporting needs are read-only and fit the provided verbs; the raw query escape hatch covers the long tail of custom HogQL without forcing you off the package.
• Internal/admin reporting and customer-facing metrics. POSTHOG_HOST plus US/EU/self-hosted support means the same code path works for a SaaS on PostHog Cloud and an enterprise deployment that must keep analytics data in its own infrastructure — a real procurement unblocker.
• Reliability and on-call decisions. Typed AuthenticationException, RateLimitException and PostHogException let engineering degrade gracefully (stale cache, hidden widget) rather than 500 the page. This is the difference between "analytics is a nice-to-have that can fail silently" and "analytics can take down the dashboard," and it should be an explicit acceptance criterion in the spec.
• Security/credential posture. The personal API key is encrypted at rest via spatie/laravel-settings and seeded from env, which shortens the security review conversation versus a bespoke implementation storing a key in plain config.
• Scoping decisions to make deliberately. This is a query client, not an ingestion client — event capture still belongs to PostHog's own SDK. Also note it requires a personal API key (broad account-level scope) rather than a project-scoped key; that should be a conscious risk acceptance, not an accident.

When to Consider This Package

Adopt when most of these hold:

• You are on PHP 8.2+ and Laravel 11, 12 or 13 — this is a hard floor and rules out the LTS-strapped part of the estate.
• You already treat PostHog as the source of truth for web analytics and want to surface it inside your Laravel app (admin panel, customer portal, internal weekly-digest job).
• Your needs are read-only and largely covered by the nine provided verbs; custom questions can live behind query.
• You are comfortable adding spatie/laravel-settings and its settings table/migration to the application — it is a reasonable but non-trivial architectural dependency for a reporting feature.
• You can provision a personal API key and accept its scope, and you have a plan for key rotation.

Look elsewhere or wait when:

• You need event capture / instrumentation — use PostHog's own SDK; this package does not do it.
• You need feature flags, experiments or session replay — adjacent PostHog surfaces, not covered here.
• You are on Laravel 10 or older, or PHP 8.1, or you maintain a package that must support a wide matrix.
• You need caching, retry/backoff, queued/batched queries or a circuit breaker out of the box — none are advertised in 1.0.0, so budget for wrapping calls yourself, especially for realtimeVisitors.
• You are not on PostHog, or you need analytics that survive a PostHog outage as the primary data path (this is a read-through client, not a warehouse).
• Maturity matters more than fit — 1.0.0 is day-one software with no support history, no deprecation policy and an unknown maintainer bus factor. That is an acceptable risk for an internal dashboard, a poor one for a revenue-facing SLA.

How to Pitch It (Stakeholders)

To executives: We can put product analytics directly inside our own product — traffic trends, top pages, acquisition sources, geography, device/browser mix and live visitor counts — without sending users to a third-party dashboard and without building an analytics backend. It is a small, single-purpose Laravel package, it works with PostHog Cloud in the US or EU or with a self-hosted instance (which matters for data-residency conversations), credentials are encrypted at rest, and failures surface as typed errors we can handle so analytics never takes down a page. The trade-off is honest: it is a first release, it only reads data (we still use PostHog's SDK to collect it), and it requires a personal API key with account-level scope.

To engineering: A typed facade over PostHog's HogQL query API — nine opinionated methods plus a raw query escape hatch, config seeded from POSTHOG_PERSONAL_API_KEY / POSTHOG_PROJECT_ID / POSTHOG_HOST, key encrypted via spatie/laravel-settings. Requires PHP 8.2+ and Laravel 11–13. What it does not give us: caching, retries/backoff, batching, or any ingestion. Plan to wrap calls in our own cache and resilience layer, particularly for the realtime widget, and treat the personal API key as a scoped secret with a rotation story before this goes anywhere near production.