README

The Laravel-native PostHog experience. LaraHog wraps the PostHog PHP SDK into a first-class Laravel package with multi-connection support, queue-based dispatch, and Octane compatibility out of the box.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13

Support us

We invest a lot of resources into creating awesome software. You can support us by sponsoring us on GitHub.

Installation

composer require temperbit/larahog

Publish the config file:

php artisan vendor:publish --tag="larahog-config"

Add your PostHog project token to .env:

POSTHOG_PROJECT_TOKEN=phc_your_project_token

Configuration

The published config file will be at config/larahog.php.

Multi-connection support

You can define multiple PostHog connections for different projects:

// config/larahog.php
'connections' => [
    'default' => [
        'project_token' => env('POSTHOG_PROJECT_TOKEN'),
        // ...
    ],
    'marketing' => [
        'project_token' => env('POSTHOG_MARKETING_TOKEN'),
        // ...
    ],
],

Then target a specific connection:

LaraHog::connection('marketing')->capture('user-123', 'campaign_clicked');

Usage

Capturing events

use TemperBit\LaraHog\Facades\LaraHog;

// Basic event
LaraHog::capture('user-123', 'page_viewed');

// With properties
LaraHog::capture('user-123', 'purchase_completed', [
    'amount' => 49.99,
    'currency' => 'USD',
]);

// With group association
LaraHog::capture('user-123', 'report_exported', [], [
    'company' => 'company-456',
]);

// Anonymous event
LaraHog::capture(null, 'landing_page_viewed');

Identifying users

LaraHog::identify('user-123', [
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
    'plan' => 'enterprise',
]);

Aliasing identities

LaraHog::alias('user-123', 'anonymous-session-abc');

Group identities

LaraHog::groupIdentify('company', 'company-456', [
    'name' => 'Acme Corp',
    'industry' => 'SaaS',
]);

Flushing

LaraHog automatically flushes pending events when the application terminates. You can also flush manually:

LaraHog::flush();    // Flush the default connection
LaraHog::flushAll(); // Flush all connections

Checking status

if (LaraHog::isEnabled()) {
    // ...
}

Dispatch Modes

Sync (default)

Events are buffered in memory by the PostHog SDK and sent in batches at the end of the request lifecycle. This is the simplest setup and works well for most applications.

POSTHOG_DISPATCH_MODE=sync

Queue

Events are dispatched to a Laravel queue for asynchronous processing. This moves PostHog API calls out of the request path entirely.

POSTHOG_DISPATCH_MODE=queue
POSTHOG_QUEUE_CONNECTION=redis
POSTHOG_QUEUE_NAME=analytics

Octane Compatibility

LaraHog uses a PostHog\Client instance (not the static PostHog::init() method), so each request gets a clean state. Multi-connection support is handled through the LaraHogManager singleton, which lazily resolves connections. This design is safe to use with Laravel Octane.

Artisan Commands

larahog:status

Displays the current configuration and tests connectivity to PostHog:

php artisan larahog:status
php artisan larahog:status --connection=marketing

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

• TemperBit
• Anand Capur
• All Contributors

License

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