Laravel PostHog

A PHP/Laravel client for PostHog. Capture events, batch ingestion, identify people, evaluate feature flags and read back persons, insights, session recordings and HogQL queries — through a simple, typed API built on Laravel's Http client. Works with PostHog Cloud (US/EU) and self-hosted instances.

Features

• Event capture: single events and batched ingestion
• Person identification: $identify and $create_alias helpers over the capture endpoint
• Feature flags: read every flag for a person, a single flag value (including multivariate variants), or a simple boolean check
• Persons: look people up by distinct_id
• HogQL: run SQL-like queries against your event data
• Insights and session recordings: list them from the project API
• Handles PostHog's two auth models for you — the public project API key in the payload for ingestion, the personal API key as a Bearer token for reads
• Throws PostHogException (with the original API error body) on any non-2xx response

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-posthog

Publish the config file:

php artisan vendor:publish --tag=posthog-config

Then set your credentials:

POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_PROJECT_API_KEY=phc_your_project_api_key
POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key
POSTHOG_PROJECT_ID=12345

POSTHOG_PROJECT_API_KEY is the public write-only key and is all you need for capture, batch and feature flags. POSTHOG_PERSONAL_API_KEY plus POSTHOG_PROJECT_ID are only required for the read endpoints (persons, HogQL, insights, session recordings).

Configuration

// config/posthog.php
return [
    'host' => env('POSTHOG_HOST', 'https://app.posthog.com'),
    'project_api_key' => env('POSTHOG_PROJECT_API_KEY', ''),
    'personal_api_key' => env('POSTHOG_PERSONAL_API_KEY', ''),
    'project_id' => env('POSTHOG_PROJECT_ID', ''),
    'timeout' => env('POSTHOG_TIMEOUT', 10),
];

Usage

The package is resolved via the PostHog facade or by injecting JeffersonGoncalves\PostHog\PostHog.

Capturing events

use JeffersonGoncalves\PostHog\Facades\PostHog;

PostHog::capture('signup_completed', 'user_123', [
    'plan' => 'pro',
    '$current_url' => 'https://example.com/signup',
]);

Batching events

PostHog::batch([
    ['event' => 'pageview', 'distinct_id' => 'user_1'],
    ['event' => 'signup', 'distinct_id' => 'user_2'],
]);

Identifying people

PostHog::identify('user_123', [
    'email' => 'user@example.com',
    'plan' => 'pro',
]);

// Merge an anonymous session into an identified person
PostHog::alias('user_123', 'anon_abc');

Feature flags

// Every flag evaluated for this person
$flags = PostHog::featureFlags('user_123');

// A single flag: false when off, true when on, the variant key when multivariate
$variant = PostHog::featureFlag('new-pricing', 'user_123');

// Simple boolean check (a variant counts as enabled)
if (PostHog::isFeatureEnabled('new-pricing', 'user_123')) {
    // Show new pricing
}

Group-based flags are supported by passing the groups map:

PostHog::isFeatureEnabled('beta-dashboard', 'user_123', ['company' => 'acme-inc']);

Persons

$persons = PostHog::persons('user_123');

HogQL queries

$result = PostHog::query(
    'SELECT event, count() FROM events WHERE timestamp > now() - interval 7 day GROUP BY event ORDER BY count() DESC LIMIT 10'
);

Insights and session recordings

$insights = PostHog::insights();

$recordings = PostHog::sessionRecordings(['limit' => 20]);

Error handling

Any non-2xx API response throws JeffersonGoncalves\PostHog\Exceptions\PostHogException, which exposes the decoded error body:

use JeffersonGoncalves\PostHog\Exceptions\PostHogException;

try {
    PostHog::persons('user_123');
} catch (PostHogException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.