Laravel Metrics Posthog Laravel Package

Getting Started

Install the package with Composer, then configure the PostHog personal API key, project ID, and host. Because settings are backed by spatie/laravel-settings, expect to publish/run the package’s settings migration and seed/update the settings record from env.

POSTHOG_PERSONAL_API_KEY=phx_...
POSTHOG_PROJECT_ID=12345
POSTHOG_HOST=https://us.posthog.com
# EU: https://eu.posthog.com
# Self-hosted: https://posthog.example.com

First checks:

1. Confirm the personal API key is a query-capable PostHog personal API key, not the public project ingestion key.
2. Confirm POSTHOG_PROJECT_ID is the numeric project ID, not the project API key.
3. Run a smoke test against a known event, e.g. pageviews for the last 7 days or realtimeVisitors.
4. Look first at the package settings class and the PostHog facade methods; use the PostHog HogQL/query docs when building raw queries.

First practical use case: a small internal analytics page showing pageviews over time, top pages, referrers, and current visitors. Use the canned facade methods first; drop to PostHog::query($hogql) only when the canned helpers do not cover the metric.

Implementation Patterns

Wrap the facade in an application service. Keep PostHog calls out of controllers and Blade templates so you can cache, retry, mock, and normalize responses.

final class Analytics
{
    public function pageviewsLast7Days(): array
    {
        return cache()->remember(
            'analytics.pageviews.7d',
            now()->addMinutes(10),
            fn () => PostHog::aggregate('$pageview', now()->subDays(7), now()),
        );
    }

    public function realtime(): int
    {
        return cache()->remember(
            'analytics.realtime',
            now()->addSeconds(15),
            fn () => PostHog::realtimeVisitors(),
        );
    }
}

Use canned helpers for dashboards and tables. A typical dashboard maps cleanly to the facade:

• timeseries for charts over time.
• breakdown for property-level comparisons.
• pages, sources, countries, browsers, devices for table widgets.
• aggregate for single-number cards.
• realtimeVisitors for a live badge or status indicator.
• query for custom HogQL metrics, cohorts, or dimensions not covered by helpers.

Cache aggressively and warm on schedule. Analytics queries are remote API calls and are rate-limited. Cache dashboard reads for 5–15 minutes and realtime for 10–30 seconds. A scheduled command can refresh common widgets so user requests never wait on PostHog.

Schedule::command('analytics:warm')->everyFiveMinutes();

Expose analytics through your own JSON endpoints. For Livewire, Inertia, or Vue/React dashboards, return normalized arrays/DTOs from your service. Never call the facade from frontend code, and never expose the personal API key.

Handle exceptions at the boundary. Let AuthenticationException surface as a configuration problem, back off on RateLimitException, and catch PostHogException to return stale cached data or a degraded widget rather than breaking the page.

try {
    return $this->analytics->pageviewsLast7Days();
} catch (RateLimitException $e) {
    return cache()->get('analytics.pageviews.7d', []);
} catch (PostHogException $e) {
    report($e);
    return [];
}

Use raw HogQL for custom product metrics. For example, group by a custom event property, filter by host/path, or build a metric the canned helpers do not expose. Keep raw queries in one class, version them, and test them against a staging PostHog project.

Separate environments. Use distinct PostHog projects or at least distinct settings records per environment. Do not let local/staging dashboards query production analytics unless that is deliberate.

Gotchas and Tips

• This package queries PostHog; it does not ingest events. You still need posthog-js or a backend capture integration to send pageviews/events.
• The personal API key is sensitive. It is encrypted by spatie/laravel-settings, but it must never reach the browser. Scope the key as narrowly as PostHog allows.
• Wrong host is a common failure. US, EU, and self-hosted instances use different base URLs. A key from one region will not work against another.
• Rate limits and query cost are real. Cache dashboard reads, avoid unbounded date ranges, and be careful with high-cardinality breakdowns.
• realtimeVisitors is approximate and laggy. Use it for presence/status, not billing, SLA, or exact reporting.
• Timezone boundaries matter. PostHog project timezone and Laravel app timezone can disagree. Be explicit about date ranges and compare “last 7 days” results with the PostHog UI.
• HogQL is not full SQL. Raw queries are tied to PostHog’s query API and supported schema. Keep them small and test them in PostHog first.
• Settings caching can confuse configuration changes. After changing env/settings, clear Laravel config/settings caches and confirm the settings record was updated.
• Facade method signatures are the contract. Use IDE completion/reflection or the package README for exact arguments; the canned helpers are convenient but less flexible than raw query.
• Extension point: your own analytics service. Bind an interface in the container and swap the PostHog implementation for a fake in tests. If the package uses Laravel’s HTTP client, Http::fake() can also isolate tests from the live API.