posthog-integration-laravel_skill

Overview

This skill integrates PostHog analytics into Laravel applications to capture events, identify users, and track errors. It provides a clear, minimal-change approach that follows an example project pattern and uses environment variables for safe configuration. The goal is predictable, maintainable analytics without scattering calls across controllers.

How this skill works

The integration creates a dedicated PostHogService in app/Services and initializes the SDK once via PostHog::init(). It registers configuration in config/posthog.php using env() for api_key, host, and disabled flags. Controllers and services call PostHogService::capture or ::identify explicitly at action points; headers X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID are forwarded when present to correlate client and server events.

When to use it

• Add analytics to new or existing Laravel projects that need event tracking and user identification
• Instrument login, signup, checkout, and other critical user flows
• Correlate frontend and backend events using distinct and session IDs
• Capture errors and important API boundary events for diagnostics
• When you need a minimal, maintainable analytics footprint that follows an example implementation

Best practices

• Store PostHog credentials and host in environment variables; never hardcode keys
• Create a single PostHogService in app/Services and route all capture/identify calls through it
• Register all SDK settings in config/posthog.php using env() and respect a disabled flag
• Initialize the PHP SDK once with PostHog::init() and use static SDK methods for capture and identify
• Call capture explicitly where actions occur; avoid using Laravel events or observers for analytics
• Follow the example project patterns and check composer.json and vendor after composer install

Example use cases

• Track user signup and login: call identify during auth flows and capture signup/login events
• E-commerce checkout: capture cart events, payment success/failure, and attach user distinctId
• Error monitoring: call capture on exceptions in API controllers to surface issues in PostHog
• Frontend/backend correlation: forward X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers from client to server to join sessions
• Feature usage: instrument feature entry points (routes or service methods) through the PostHogService