Laravel Posthog Laravel Package

Technical Evaluation

Architecture fit

• Thin SDK over PostHog's public HTTP APIs, mapping cleanly onto Laravel's container, config, and exception conventions. No infrastructure to operate — it is a client, not a pipeline.
• The two-plane split is the right seam: ingestion (project API key in payload, high-volume, fire-and-forget) is cleanly separated from the project API (personal API key as Bearer, read/query path). This lets us adopt capture without ever touching the privileged key.
• It is explicitly not a resilience layer: no local buffering, no queue worker, no local flag evaluation. All retry, batching, timeout, and fallback behaviour has to be supplied by the host application.

Integration feasibility

• Capture is low-friction: one project key, identify/alias helpers, batch endpoint available. A single service could ship this in a day.
• Feature flags, person lookup, HogQL, insights, and recordings all require a personal API key — a privileged, broad-scope secret in the application environment. This is the gating item for security/platform review, not the code.
• Value is front-loaded: teams get flags and analytics from one dependency rather than two integrations.

Technical risk

• Per-call remote evaluation. No local evaluation or polling is described, so every flag check is plausibly a network round-trip inside a request path. That is a latency cost and a hard runtime dependency on a third party.
• Unspecified delivery semantics. Batching exists, but flush triggers, retry/backoff policy, timeouts, and sync-vs-async capture are undocumented. Event loss is silent by nature.
• Fresh 1.0.0. No stated PHP/Laravel compatibility matrix, no mention of a service provider, facade, publishable config, or test double. Expect 1.x churn.
• Privileged secret sprawl. A personal API key in app config, with no documented scoping, expands blast radius if leaked.
• Data residency / PII. No mention of host configuration (US/EU/self-hosted) or redaction hooks, while the package's core job is shipping user identifiers and properties to a third party.

Key questions

• Which PHP and Laravel versions are supported, and is there a CI matrix?
• Are capture calls synchronous by default? Is there a queue job or terminable-middleware path?
• Are timeouts and retries configurable, and are capture retries idempotent (uuid/dedup) so batching doesn't double-count?
• Does flag evaluation support local evaluation or a TTL cache, or is every check a live call?
• What key scopes are required per feature, and can flags / HogQL / recordings be independently disabled?
• Is the PostHog host configurable for EU residency or self-hosting?
• Is there a fake/test double so our suite doesn't hit the network?
• How are partial batch failures surfaced — does PostHogException cover 207-style partial success?

Integration Approach

Stack fit

• Conventional Laravel install: Composer, service provider auto-discovery, config via env and secret manager. Ingestion key can live in normal app config; the personal API key must go to the secret store with least-privilege scopes and a rotation owner.

Migration path

• Greenfield — no incumbent analytics client to displace. Do not wire the package directly into call sites. Wrap it behind a small in-house AnalyticsClient / FeatureFlags interface (capture, identify, flag check, fallback default) so a future vendor swap or a 1.x breaking change touches one class instead of dozens of call sites.

Compatibility

• Verify PHP/Laravel constraints against the fleet before pinning; pin to ~1.0.0 and treat flag and query signatures as unstable until ~1.2.
• Two auth models mean two config surfaces and two failure domains. Keep them separately toggleable so ingestion can stay on while project-API features are disabled.

Sequencing

1. Capture + identify/alias only, in one low-traffic service, behind a kill switch.
2. Add boolean flag checks for a non-critical flag, with a hard-coded default in the catch path, and measure added latency.
3. Expand to multivariate and group flags once latency and fallback behaviour are understood.
4. Treat HogQL, insights, and session recordings as back-office surface — scheduled jobs or internal tooling, never a user request path.
5. Broaden adoption only after the wrapper and the fail-open policy are proven.

Operational Impact

Maintenance

• Fresh 1.0.0 implies a small maintainer base and likely API churn. Pin the version, subscribe to releases, budget a quarterly review. The wrapper interface is the hedge against breaking changes.

Support

• Three-way support surface: package author, PostHog, and our on-call. Our on-call owns integration-level failures regardless of origin. Runbook needs explicit entries for "flags unavailable" and "capture silently failing."

Scaling

• Ingestion cost scales linearly with traffic — batch and consider dispatching capture from queue workers on hot paths.
• Flag evaluation is the real scaling concern. If each check is a round-trip, N checks per request multiply outbound calls. Mandate per-request memoization plus a short-TTL local cache, and push upstream for local evaluation. Watch for 429s under load with no documented backoff.

Failure modes

• PostHog outage → flag checks fail. Must fail open to a static default so a third party cannot take down checkout. This is a design decision, not a library feature.
• Asymmetric auth failure. Personal key expiry breaks flags/HogQL while ingestion keeps working — easy to misdiagnose. Alert on project-API errors distinctly from ingestion errors.
• Silent event loss. Partial batch failures and non-2xx capture responses must be logged and metered, never surfaced to users.
• Log leakage. PostHogException carrying the raw API error body is excellent for debugging and risky in logs — scrub payloads and keys before logging.

Ramp-up

• Low for any Laravel developer; the helpers are self-explanatory. The non-obvious parts — two-key model, sync vs async capture, fail-open defaults — need a one-page internal standard and the shared wrapper, otherwise each team invents its own fallback semantics and flag behaviour becomes inconsistent across the product.

Recommendation: Adopt for capture now; gate feature flags behind a latency spike and a written fail-open policy; keep HogQL/recordings out of request paths; treat the personal API key as a tier-1 secret.