playbooks

home / skills / openagentsinc / openagents / posthog-integration-laravel

posthog-integration-laravel skill

/apps/openagents.com/.claude/skills/posthog-integration-laravel

This skill helps you integrate PostHog analytics into Laravel apps with minimal changes and environment-based configuration.

npx playbooks add skill openagentsinc/openagents --skill posthog-integration-laravel

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
2.7 KB
---
name: integration-laravel
description: PostHog integration for Laravel applications
metadata:
  author: PostHog
  version: 1.5.2
---

# PostHog integration for Laravel

This skill helps you add PostHog analytics to Laravel applications.

## Workflow

Follow these steps in order to complete the integration:

1. `basic-integration-1.0-begin.md` - PostHog Setup - Begin ← **Start here**
2. `basic-integration-1.1-edit.md` - PostHog Setup - Edit
3. `basic-integration-1.2-revise.md` - PostHog Setup - Revise
4. `basic-integration-1.3-conclude.md` - PostHog Setup - Conclusion

## Reference files

- `EXAMPLE.md` - Laravel example project code
- `laravel.md` - Laravel - docs
- `identify-users.md` - Identify users - docs
- `basic-integration-1.0-begin.md` - PostHog setup - begin
- `basic-integration-1.1-edit.md` - PostHog setup - edit
- `basic-integration-1.2-revise.md` - PostHog setup - revise
- `basic-integration-1.3-conclude.md` - PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

## Key principles

- **Environment variables**: Always use environment variables for PostHog keys. Never hardcode them.
- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
- **Match the example**: Your implementation should follow the example project's patterns as closely as possible.

## Framework guidelines

- Create a dedicated PostHogService class in app/Services/ - do NOT scatter PostHog::capture calls throughout controllers
- Register PostHog configuration in config/posthog.php using env() for all settings (api_key, host, disabled)
- Do NOT use Laravel's event system or observers for analytics - call capture explicitly where actions occur
- Remember that source code is available in the vendor directory after composer install
- posthog/posthog-php is the PHP SDK package name
- Check composer.json for existing dependencies and autoload configuration before adding new files
- The PHP SDK uses static methods (PostHog::capture, PostHog::identify) - initialize once with PostHog::init()
- PHP SDK methods take associative arrays with 'distinctId', 'event', 'properties' keys - not positional arguments

## Identifying users

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` headers to maintain correlation.

## Error tracking

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

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

FAQ

How should I pass API keys to the app?

Keep keys in .env and reference them in config/posthog.php with env(). Do not commit keys to version control.

Where should I put PostHog calls?

Use a single PostHogService in app/Services. Call capture/identify explicitly from controllers or services where actions occur; do not scatter PostHog::capture across the codebase.