Skip to content

feat(examples): use the posthog laravel sdk in the laravel example - #497

Merged
rafaeelaudibert merged 4 commits into
feat/install-skill-new-examplesfrom
feat/laravel-sdk-example
Nov 10, 2026
Merged

rafaeelaudibert merged 4 commits into
feat/install-skill-new-examplesfrom
feat/laravel-sdk-example

Conversation

@rafaeelaudibert

@rafaeelaudibert rafaeelaudibert commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Problem

The Laravel example wires the plain PHP SDK by hand: its own init, request middleware, exception callback, config file and wrapper service. Agents copy it, so Laravel 12 and 13 apps get that hand-wiring instead of posthog/posthog-laravel, which does all of it.

Changes

  • Example: Laravel 12 and posthog/posthog-laravel, set up with composer require and php artisan posthog:install. The init, middleware, exception callback and PostHogService are gone.
  • Token name: POSTHOG_API_KEY, the name the released SDK reads, with the stock published config. feat: read the project token from POSTHOG_PROJECT_TOKEN posthog-php#311 moves the SDK to POSTHOG_PROJECT_TOKEN, the name the other examples use. Once it ships, this example and the Laravel rules switch to it.
  • Calls: the PostHog facade throughout.
    • Login and signup identify with the user's primary key.
    • Other captures and flag checks take the signed-in user from the request.
  • Docs: the README, the implementation notes and the code shown in the UI match the new calls. The README says Laravel 11 and earlier use the PHP SDK's manual setup.
  • Rules: the Laravel commandments and the PHP best practices point agents at the SDK on Laravel 12+. They keep the manual setup for older apps and drop the "wrap PostHog in a service" rule.
  • Signed-out visitors: the sdk-install rule now keeps an integration's own handling. The Laravel SDK sends each signed-out event with a fresh personless id.
  • Fixed along the way: routes/api.php used auth:sanctum without Sanctum installed, so both API routes failed. They now use session auth.

The Laravel SDK is labelled experimental on its docs page, which still offers the manual setup.

Stacked on #495.

How it was checked

Check Result
composer install and composer audit in Docker Clean. This also clears the open dependency advisories on the old Laravel 11 lock
Boot with a blank key /, /register and /up return 200. posthog:doctor reports PostHog disabled
Fake PostHog host, signed in as the seeded user Login, signup, burrito, dashboard flags, exceptions and logout events all carry the user's id. Flags render their payload
Signed-out request Personless random id per event
Skills npm test (320 passed) and npm run build

Not run: delivery to a real PostHog project.

Agent context

Written by Claude Opus 5.5 (claude-opus-5-5) in Claude Code. A Sonnet agent drafted the example port and ran the fake-host checks, and Opus reviewed it and wrote the rule changes.

🤖 Generated with Claude Code

The Laravel example moves to Laravel 12 and posthog/posthog-laravel,
which replaces its hand-written init, middleware, exception callback and
wrapper service. The Laravel rules and PHP best practices point agents at
the SDK on Laravel 12+ and keep the manual PHP SDK setup for older apps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rafaeelaudibert
rafaeelaudibert requested a review from a team as a code owner November 10, 2026 05:42
@github-actions

Copy link
Copy Markdown

🧙 Wizard CI

Run the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands:

Test all apps:

  • /wizard-ci all

Test all apps in a directory:

  • /wizard-ci ai-observability
  • /wizard-ci basic-integration
  • /wizard-ci feature-flags
  • /wizard-ci mcp-analytics
  • /wizard-ci replay-vision
  • /wizard-ci revenue
  • /wizard-ci self-driving
  • /wizard-ci warehouse
  • /wizard-ci warehouse-seeded

Test an individual app:

  • /wizard-ci ai-observability/anthropic
  • /wizard-ci ai-observability/google-adk
  • /wizard-ci ai-observability/groq
Show more apps
  • /wizard-ci ai-observability/manual-capture
  • /wizard-ci ai-observability/openai
  • /wizard-ci ai-observability/openai-agents
  • /wizard-ci ai-observability/opentelemetry
  • /wizard-ci ai-observability/vercel-ai
  • /wizard-ci basic-integration/android
  • /wizard-ci basic-integration/angular
  • /wizard-ci basic-integration/astro
  • /wizard-ci basic-integration/django
  • /wizard-ci basic-integration/fastapi
  • /wizard-ci basic-integration/flask
  • /wizard-ci basic-integration/flutter
  • /wizard-ci basic-integration/javascript-node
  • /wizard-ci basic-integration/javascript-web
  • /wizard-ci basic-integration/laravel
  • /wizard-ci basic-integration/next-js
  • /wizard-ci basic-integration/nuxt
  • /wizard-ci basic-integration/python
  • /wizard-ci basic-integration/rails
  • /wizard-ci basic-integration/react-native
  • /wizard-ci basic-integration/react-router
  • /wizard-ci basic-integration/sveltekit
  • /wizard-ci basic-integration/swift
  • /wizard-ci basic-integration/tanstack-router
  • /wizard-ci basic-integration/tanstack-start
  • /wizard-ci basic-integration/vue
  • /wizard-ci feature-flags/django
  • /wizard-ci feature-flags/next-js
  • /wizard-ci mcp-analytics/custom-dispatcher
  • /wizard-ci mcp-analytics/go-sdk
  • /wizard-ci mcp-analytics/python-sdk
  • /wizard-ci mcp-analytics/ruby-sdk
  • /wizard-ci mcp-analytics/rust-sdk
  • /wizard-ci mcp-analytics/typescript-sdk
  • /wizard-ci replay-vision/javascript-node
  • /wizard-ci replay-vision/next-js
  • /wizard-ci replay-vision/react-vite
  • /wizard-ci revenue/stripe
  • /wizard-ci self-driving/astro
  • /wizard-ci self-driving/fastapi
  • /wizard-ci self-driving/nuxt
  • /wizard-ci self-driving/react-router
  • /wizard-ci self-driving/sveltekit
  • /wizard-ci warehouse/monorepo-env
  • /wizard-ci warehouse/multi-source-next
  • /wizard-ci warehouse/stripe-node
  • /wizard-ci warehouse/zero-source
  • /wizard-ci warehouse-seeded/next-stripe
  • /wizard-ci warehouse-seeded/next-stripe-declined

Test against a wizard branch:

  • /wizard-ci all wizard:my-branch

Add wizard:<branch> to any command above to pin the wizard branch. It defaults to main.

Results will be posted here when complete.

rafaeelaudibert and others added 2 commits November 10, 2026 02:45
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he token name

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rafaeelaudibert

Copy link
Copy Markdown
Member Author

Eval results behind this stack

The changes in this stack came from running PostHog's install skills against real apps and grading each run. This comment has every result.

What we ran

  • Question: do coding agents install PostHog better with one all-in-one skill ("firehose", the omnibus instrument-integration), or with the wizard's step-by-step tasks ("stepwise", integration-v2)?
  • Arms: both arms shared the same 127 reference files (docs pages, example apps, rules). Only SKILL.md, plus the stepwise task files, differed. A third arm, "firehose-nocmd", removed the per-framework rules files.
  • Apps: four sample apps from PostHog/wizard-workbench: Next.js 15 App Router, Django 3, Rails and Express.
  • Agents: Claude Code (Claude Opus 5.5), Codex (GPT-6.1 sol) and OpenCode (Kimi K3). 3 samples per app, arm and agent. 81 runs were judged.
  • Grading: the existing install rubric for those apps, plus a check that a missing PostHog key never breaks the app.
    • Sound means every rubric criterion passed, except the scope ones.
    • Went past install is sc_install_only: the agent added things the task didn't ask for, such as exception capture or custom events.
    • Any scope miss also counts as_minimal_changes and fa_no_unnecessary_changes.
  • Cost and minutes are per run, from the eval runner.

Findings and where the stack addressed them

Finding Addressed in
Neither shape clearly wins. Firehose was sound in 21/24 frontier runs and stepwise in 23/24; all 3 firehose misses were Claude Code No change of shape. hog will serve the firehose skill
Agents copy the example apps closely, including extras like exception capture and events on every route. Removing the per-framework rules files barely changed it (6/8 still went past install) #491 asks agents to list extras from the example. #495 and #497 add missing framework examples, so agents copy a correct one
Missing env template, or init that breaks without a key #491 (env step), #493 (examples boot without a token)
A second lockfile left stale (Rails) #491
About a third of Next.js runs copied an old defaults preset from the examples #491 (take defaults from the docs), #493 (every browser example on '2026-08-30')
Few Next.js runs set up or suggested a reverse proxy #491, #493 (region-aware proxies in the examples)
Codex fetched posthog.com docs in most runs, while Claude Code never left the skill #494 adds the 14 SDK pages the skills were missing
No shared install rules for identity, server clients, CSP and multi-platform init #494 (sdk-install rules)

Frontier agents, main arms

Arm Runs Sound Went past install Any scope miss Fetched posthog.com docs Median minutes Median cost Median tool calls
firehose 24 21/24 20/24 22/24 11/24 3.8 $0.46 23
stepwise 24 23/24 13/24 18/24 10/24 3.5 $0.45 23

By agent and arm (frontier)

Agent and arm Runs Sound Went past install Any scope miss Fetched posthog.com docs Median minutes Median cost Median tool calls
Claude Code (Opus 5.5), firehose 12 9/12 11/12 11/12 0/12 3.0 $0.54 18
Claude Code (Opus 5.5), stepwise 12 12/12 6/12 6/12 0/12 3.1 $0.61 21
Codex (GPT-6.1 sol), firehose 12 12/12 9/12 11/12 11/12 4.4 $0.41 25
Codex (GPT-6.1 sol), stepwise 12 11/12 7/12 12/12 10/12 3.5 $0.41 27

By app and arm (frontier)

App and arm Runs Sound Went past install Any scope miss Fetched posthog.com docs Median minutes Median cost Median tool calls
Next.js 15 App Router, firehose 6 5/6 6/6 6/6 3/6 4.0 $0.54 26
Next.js 15 App Router, stepwise 6 5/6 5/6 6/6 3/6 5.7 $0.71 31
Django 3, firehose 6 6/6 5/6 5/6 3/6 3.2 $0.41 18
Django 3, stepwise 6 6/6 0/6 3/6 2/6 2.6 $0.41 20
Rails, firehose 6 4/6 3/6 5/6 3/6 11.6 $1.14 52
Rails, stepwise 6 6/6 2/6 3/6 3/6 4.7 $0.84 34
Express, firehose 6 6/6 6/6 6/6 2/6 2.3 $0.28 16
Express, stepwise 6 6/6 6/6 6/6 2/6 2.5 $0.36 20

Next.js reverse proxy (set up or suggested): firehose 2/6, stepwise 5/6

Firehose without the per-framework rules files (frontier, Next.js and Django)

Arm Runs Sound Went past install Any scope miss Fetched posthog.com docs Median minutes Median cost Median tool calls
firehose-nocmd 8 7/8 6/8 6/8 4/8 3.4 $0.41 22

OpenCode (Kimi K3), secondary

Arm Runs Sound Went past install Any scope miss Fetched posthog.com docs Median minutes Median cost Median tool calls
firehose 12 11/12 11/12 11/12 0/12 12.0 $0.94 56
stepwise 11 10/11 7/11 7/11 1/11 11.6 $1.20 56
firehose-nocmd 2 1/2 2/2 2/2 0/2 6.7 $0.52 36
Every judged run
App Arm Agent Soundness criteria failed Scope criteria failed Next.js proxy Docs fetched Minutes Cost
Django 3 firehose Claude Code (Opus 5.5) none none no 2.3 $0.39
Django 3 firehose Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 2.7 $0.43
Django 3 firehose Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 2.4 $0.53
Django 3 firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.8 $0.36
Django 3 firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.8 $0.37
Django 3 firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 5.0 $0.46
Django 3 firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 30.2 $1.06
Django 3 firehose OpenCode (Kimi K3) none none no 7.3 $0.64
Django 3 firehose OpenCode (Kimi K3) none as_minimal_changes, fa_no_unnecessary_changes, sc_install_only no 8.5 $1.08
Django 3 firehose-nocmd Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 2.0 $0.31
Django 3 firehose-nocmd Claude Code (Opus 5.5) none none no 1.8 $0.43
Django 3 firehose-nocmd Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.8 $0.39
Django 3 firehose-nocmd Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.7 $0.38
Django 3 firehose-nocmd OpenCode (Kimi K3) ph_missing_config_safe as_minimal_changes, sc_install_only no 7.3 $0.53
Django 3 stepwise Claude Code (Opus 5.5) none none no 2.4 $0.41
Django 3 stepwise Claude Code (Opus 5.5) none none no 2.5 $0.49
Django 3 stepwise Claude Code (Opus 5.5) none none no 2.4 $0.45
Django 3 stepwise Codex (GPT-6.1 sol) none as_minimal_changes, fa_no_unnecessary_changes yes 2.7 $0.30
Django 3 stepwise Codex (GPT-6.1 sol) none as_minimal_changes yes 3.0 $0.35
Django 3 stepwise Codex (GPT-6.1 sol) none as_minimal_changes no 3.4 $0.41
Django 3 stepwise OpenCode (Kimi K3) none none no 11.6 $1.68
Django 3 stepwise OpenCode (Kimi K3) none none no 7.8 $0.77
Django 3 stepwise OpenCode (Kimi K3) none none no 8.5 $0.91
Express firehose Claude Code (Opus 5.5) none sc_install_only no 1.5 $0.23
Express firehose Claude Code (Opus 5.5) none sc_install_only no 1.7 $0.24
Express firehose Claude Code (Opus 5.5) none sc_install_only no 1.9 $0.31
Express firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.1 $0.31
Express firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only no 2.8 $0.30
Express firehose Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 2.7 $0.27
Express firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 2.5 $0.28
Express firehose OpenCode (Kimi K3) as_preserves_existing as_minimal_changes, sc_install_only no 4.7 $0.63
Express firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 2.8 $0.47
Express stepwise Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 1.9 $0.39
Express stepwise Claude Code (Opus 5.5) none sc_install_only no 2.4 $0.47
Express stepwise Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 2.2 $0.40
Express stepwise Codex (GPT-6.1 sol) none sc_install_only yes 2.6 $0.32
Express stepwise Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only no 2.7 $0.28
Express stepwise Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 2.9 $0.29
Express stepwise OpenCode (Kimi K3) as_preserves_existing as_minimal_changes, sc_install_only no 5.8 $0.43
Express stepwise OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 7.8 $0.80
Next.js 15 App Router firehose Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only missed no 4.1 $0.79
Next.js 15 App Router firehose Claude Code (Opus 5.5) ph_missing_config_safe as_minimal_changes, sc_install_only ok no 3.8 $0.67
Next.js 15 App Router firehose Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only ok no 3.4 $0.55
Next.js 15 App Router firehose Codex (GPT-6.1 sol) none sc_install_only missed yes 5.4 $0.52
Next.js 15 App Router firehose Codex (GPT-6.1 sol) none sc_install_only missed yes 3.5 $0.34
Next.js 15 App Router firehose Codex (GPT-6.1 sol) none sc_install_only missed yes 5.4 $0.45
Next.js 15 App Router firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 26.9 $0.68
Next.js 15 App Router firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 12.9 $0.81
Next.js 15 App Router firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 12.9 $1.07
Next.js 15 App Router firehose-nocmd Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only ok no 3.1 $0.51
Next.js 15 App Router firehose-nocmd Claude Code (Opus 5.5) ph_missing_config_safe sc_install_only ok no 3.0 $0.45
Next.js 15 App Router firehose-nocmd Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only missed yes 5.0 $0.44
Next.js 15 App Router firehose-nocmd Codex (GPT-6.1 sol) none none missed yes 3.6 $0.34
Next.js 15 App Router firehose-nocmd OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 6.0 $0.51
Next.js 15 App Router stepwise Claude Code (Opus 5.5) none as_minimal_changes, fa_no_unnecessary_changes, sc_install_only ok no 6.0 $0.77
Next.js 15 App Router stepwise Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only ok no 5.3 $0.73
Next.js 15 App Router stepwise Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only ok no 7.0 $0.89
Next.js 15 App Router stepwise Codex (GPT-6.1 sol) fa_code_quality as_minimal_changes, fa_no_unnecessary_changes, sc_install_only ok yes 3.6 $0.45
Next.js 15 App Router stepwise Codex (GPT-6.1 sol) none as_minimal_changes, fa_no_unnecessary_changes missed yes 4.4 $0.55
Next.js 15 App Router stepwise Codex (GPT-6.1 sol) none as_minimal_changes, fa_no_unnecessary_changes, sc_install_only ok yes 6.7 $0.68
Next.js 15 App Router stepwise OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 27.7 $1.20
Next.js 15 App Router stepwise OpenCode (Kimi K3) none sc_install_only ok no 9.7 $0.80
Next.js 15 App Router stepwise OpenCode (Kimi K3) none as_minimal_changes, sc_install_only ok no 12.0 $1.79
Rails firehose Claude Code (Opus 5.5) fa_files_complete as_minimal_changes, sc_install_only no 20.3 $1.18
Rails firehose Claude Code (Opus 5.5) as_env_documented, fa_files_complete as_minimal_changes, sc_install_only no 19.8 $3.01
Rails firehose Claude Code (Opus 5.5) none as_minimal_changes, sc_install_only no 10.3 $1.13
Rails firehose Codex (GPT-6.1 sol) none as_minimal_changes yes 9.0 $1.12
Rails firehose Codex (GPT-6.1 sol) none none yes 7.0 $0.81
Rails firehose Codex (GPT-6.1 sol) none as_minimal_changes yes 12.9 $1.14
Rails firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 11.8 $1.95
Rails firehose OpenCode (Kimi K3) none sc_install_only no 12.2 $1.63
Rails firehose OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 20.1 $2.37
Rails stepwise Claude Code (Opus 5.5) none none no 21.0 $2.54
Rails stepwise Claude Code (Opus 5.5) none none no 4.5 $1.31
Rails stepwise Claude Code (Opus 5.5) none none no 3.6 $1.09
Rails stepwise Codex (GPT-6.1 sol) none as_minimal_changes, sc_install_only yes 3.9 $0.42
Rails stepwise Codex (GPT-6.1 sol) none as_minimal_changes yes 5.0 $0.60
Rails stepwise Codex (GPT-6.1 sol) none as_minimal_changes, fa_no_unnecessary_changes, sc_install_only yes 4.9 $0.45
Rails stepwise OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 15.2 $2.13
Rails stepwise OpenCode (Kimi K3) none as_minimal_changes, sc_install_only no 18.4 $1.22
Rails stepwise OpenCode (Kimi K3) none none yes 15.6 $1.58

🤖 Generated with Claude Code

@gewenyu99 gewenyu99 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Laravel example uses POSTHOG_API_KEY because that's what the SDK reads today. We call it the project token everywhere else now, so I'm going to open a PR to fix that at the source, and then we can switch this over. Thanks!

@rafaeelaudibert
rafaeelaudibert merged commit 45bf02f into main Nov 10, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants