Weave Code
Laravel Posthog Laravel Package
qodenl/laravel-posthog
A Laravel package for integrating PostHog analytics into your app. Track events, identify users, and send data to PostHog through a simple, configurable API, making product analytics and feature flag workflows easier to add to Laravel projects.
Laravel Posthog implementation
Frequently asked questions about Laravel Posthog
- How do I install and set up qodenl/laravel-posthog?
- Install it with composer require qodenl/laravel-posthog, then publish the package configuration so you can supply your PostHog project API key and host. The service provider registers a Posthog facade, so once your environment values are in place you can call Posthog::capture() and related methods from anywhere in the application. Because everything is environment-driven, the setup keeps working after php artisan config:cache.
- Which Laravel versions does laravel-posthog support?
- Release 1.5.0 requires Laravel 12 and drops Laravel 11 support, so Composer will refuse to install it on a Laravel 11 application. Laravel 11 is out of security support, so the break is deliberate, but it does gate the upgrade on first moving lagging services to Laravel 12. If you cannot upgrade yet, pin the 1.4.x line for as long as it remains supported.
- Does the package work with config:cache and PHP-FPM?
- Yes. Configuration is resolved through Laravel's config layer rather than raw env() calls at runtime, and POSTHOG_RELEASE_ID works correctly under config:cache and PHP-FPM without setting clear_env = no. That removes a common deployment footgun where release IDs silently disappeared in production. Teams that worked around it with a custom super property or a deployed .env hack should retire those workarounds.
- How do I track a custom event with PostHog in Laravel?
- Use the Posthog facade to capture events, passing a distinct ID, an event name, and an optional properties array. The package is a thin wrapper over posthog/posthog-php, so standard PostHog event semantics and naming conventions apply. Dispatch is queue-aware, so you can move sending off the request path when latency matters.
- How do I identify users and set person properties?
- Call the identify method on the Posthog facade with the user's distinct ID and a properties array, typically right after login or registration so anonymous events merge into the correct person profile. Keep property names and value formats stable across events so cohorts, funnels, and dashboards stay consistent in PostHog. Avoid sending sensitive values as person properties unless your data policy explicitly allows it.
- Can I use getFeatureFlagPayload() for remote config?
- Yes. getFeatureFlagPayload() reads from the same cached flag evaluation as getFeatureFlag(), so it adds no extra /flags request and no new network dependency. That makes it useful for remote config and JSON payload use cases that previously required a second vendor or a bespoke table. Still gate behaviour behind the flag check itself rather than treating the payload as an independent trust boundary.
- How does error tracking work and is it enabled by default?
- Error tracking is opt-in through POSTHOG_ERROR_TRACKING_ENABLED and is off by default, which is the safer posture. When enabled, it hooks Laravel's exception handler and reports exceptions to PostHog alongside your analytics events. Because that hook sits on a hot, failure-sensitive path, monitor event volume and confirm it coexists cleanly with Sentry, Flare, or Bugsnag instead of double-reporting.
- How do I send client IPs for GeoIP, and what should I watch out for?
- Set POSTHOG_CAPTURE_IP to true to include $ip on capture, identify, and captured exception calls; the default is false. IPs are resolved from request()->ip() at dispatch time, so queued events carry the enqueuing request's IP, which is correct for GeoIP but also means IP data is persisted in your queue backend. Behind Cloudflare or another proxy, configure resolveIpUsing() or you will record edge IPs instead of real clients. Enabling this is a privacy and compliance decision, so confirm DPA or DPIA review, retention settings, and GeoIP region configuration first.
- How do I avoid sending PostHog events from local or test environments?
- The simplest approach is to leave the PostHog key unset or point the host at a no-op value in your testing environment configuration, and to mock the Posthog facade in feature tests. Because the package resolves everything through config, per-environment .env files let you use separate keys without code changes. Avoid hitting the live PostHog API from automated test suites.
- How does this compare with using posthog/posthog-php directly, and who maintains it?
- This package is a thin, opinionated Laravel wrapper around posthog/posthog-php, adding config publishing, a facade, environment-driven setup that survives config:cache, and queue-aware dispatch. If you only need a couple of raw capture calls, the upstream SDK alone is fine; the wrapper pays off when you want consistent configuration across a whole application or estate. It appears to be maintained by a single maintainer at Qode, so pin versions, review changelogs between minors, and keep an eye on release cadence and the support window.
Weaver
How can I help you explore Laravel packages today?