Laravel Posthog Laravel Package

Product Decisions This Supports

• Experimentation and server-side gating. getFeatureFlagPayload() returns a flag's decoded payload from the same cached evaluation as getFeatureFlag(), with no extra /flags request, and works under local evaluation. That makes payload-driven gating (limits, copy variants, pricing tests, config overrides) viable for high-traffic endpoints where per-request network calls or latency were previously a blocker — an "is PostHog fast enough for this?" decision becomes a yes.
• Release-level impact attribution. POSTHOG_RELEASE_ID is attached as $release_id to every event, including $feature_flag_called. This lets us answer "what did this deploy do to the funnel/flag metrics?" without building custom deploy markers or correlating timestamps. That it survives config:cache and PHP-FPM without clear_env = no removes the most common ops failure mode for this pattern.
• Tool consolidation / build vs. buy. captureException() plus opt-in handler-wide reporting means one vendor for analytics, flags, and errors instead of standing up a second integration. For a Laravel app, using this thin maintained wrapper beats owning our own glue for config caching, queue IP capture, and exception hooks.
• Data-quality decisions on geo and regional reporting. POSTHOG_CAPTURE_IP (default off) fixes the "all our users appear to be in the datacenter" problem when events are dispatched to queues, and resolveIpUsing() covers proxies like Cloudflare. Any geo/regional segmentation we've been half-trusting is now fixable — and because it's opt-in, privacy review is a scoped decision rather than a blocker.
• Roadmap constraint. Laravel 11 support was removed. This pins the baseline to Laravel 12/13; if staying on 11 is on the roadmap, this release (and future ones) are off the table and we're on 1.4.x with no security-fix runway from Laravel itself.
• Support/incident workflow. Errors and flags arriving in the same place shortens triage loops and keeps product context next to stack traces, which is a support-cost decision more than an engineering one.

When to Consider This Package

Adoption criteria:

• On Laravel 12 or 13 (required by 1.5.0+). If pinned to 11, stay on 1.4.x and treat the platform upgrade as the gating item.
• Already on PostHog, or actively standardizing on it. Without PostHog in the stack, the value collapses to "a generic event client."
• Server-side flag evaluation matters to you — latency-sensitive paths, high request volume, or a desire to cut /flags API calls. The payload + local-evaluation work is the strongest argument for this release specifically.
• You run queue workers or sit behind a CDN/proxy. The IP handling is a genuine correctness fix, not a nicety.
• You use config:cache in production (most of us do) and want release tagging to actually work.
• You want exception reporting without procuring another vendor.

Look elsewhere when:

• Laravel ≤11 with no upgrade path, or a polyglot estate where per-framework wrappers become governance debt (plain posthog-php or a standard OTel pipeline may be the better center of gravity).
• You need serious error-tracking capability — breadcrumbs, source maps, release health, alert routing, on-call integrations. This is a convenience layer; dedicated error/APM vendors remain stronger and will not be replaced by it.
• Privacy or data-residency rules forbid sending IPs or full exception data to PostHog Cloud. Self-hosting or strict consent gating must be resolved first; note capture_ip and handler-wide exception reporting both widen the data footprint.
• Your primary need is client-side autocapture/funnels — this package is server-side and complements rather than replaces the JS SDK.

Validate before adopting: interaction with any custom exception handler, whether IP capture is consistent with our privacy notice and consent state, and that queued payloads don't carry IPs where they shouldn't. Pin the version, since the posthog-php 4.14 bump shifts local-evaluation matching semantics for flags.

How to Pitch It (Stakeholders)

For executives: a small, low-risk upgrade that makes our analytics materially more useful. Experiments now resolve on our servers from cache, so we can gate features and read variant payloads without added latency or API cost. Every event is stamped with the release that produced it, so we can read the impact of a deploy instead of guessing. Errors flow into the same tool we already pay for, and geographic reporting becomes accurate even though our queue workers — not our users — were previously supplying the IP. IP collection is opt-in and off by default. The one real cost is a platform requirement: we need to be on Laravel 12 or 13.

For engineering: a minor version bump with one breaking change (Laravel 11 dropped) and four additive capabilities: getFeatureFlagPayload() reading cached/local evaluations, POSTHOG_RELEASE_ID that is config-cache and PHP-FPM safe, captureException() with opt-in handler-wide reporting, and POSTHOG_CAPTURE_IP with resolveIpUsing() for proxies like Cloudflare. No migration work beyond the framework version and deliberately enabling the new flags; explicit $release_id and $ip in event properties still take precedence, so existing call sites keep their behavior.