Thanks for your interest in improving the PostHog PHP SDK.
This repo requires all commits to be signed. To configure commit signing, see the PostHog handbook. Set commit.gpgsign to true in your git config so that every commit is signed, not only the ones you sign by hand.
-
Install PHP and Composer. Enable PHP's
zlibextension for the gzip regression tests. This is a development-only dependency, not an SDK runtime requirement. -
Install dependencies using the same command CI uses:
composer install --prefer-dist --no-progress
-
Copy
.env.exampleto.envand add your PostHog credentials. -
Run the interactive example script:
php example.php
Run the test command used in CI:
XDEBUG_MODE=coverage ./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --coverage-textThe PHPUnit transport tests use a loopback HTTP server, not live PostHog endpoints. They require the cURL extension, the curl and gzip commands, and permission to start PHP subprocesses and listen on loopback ports. Distribution archive tests also require the git and tar commands.
Run the adapter fidelity and report checker tests (Python standard library only):
python3 -m unittest discover -s sdk_compliance_adapter -vAfter the Composer install above, run PHP_CodeSniffer with the Composer-installed tool and phpcs.xml, matching CI:
./vendor/bin/phpcs --standard=phpcs.xml --extensions=php lib testpackages/laravel is an independent Composer package and a pnpm workspace project
for release metadata. Both packages record change intents in .changeset/.
Its CI covers Laravel 12 on PHP 8.2–8.5 and Laravel 13 on PHP 8.3–8.5.
From a committed checkout, run:
bash scripts/test-laravel.sh 12
bash scripts/test-laravel.sh 13The framework checks lint tracked package/example PHP files, then install and test in
an automatically cleaned temporary source copy. They inject local Composer path
repositories for the checked-out core and Laravel package there, never into your
checkout or distribution metadata. The example's composer test runs when its
composer.json is available; a missing test command then fails rather than skips.
Root PHPCS checks remain scoped to lib and test.
Record Laravel release changes with pnpm change, selecting posthog-laravel.
For core-only changes, select posthog-php: pnpm automatically adds a Laravel
patch to update its exact Composer core dependency. Select both when both packages
have code changes. One workspace version plan is committed before the packages
are published separately, core first.
See the Laravel release guide
for dependency-aware releases and required administrator setup.
Public API is hard to change once it ships, so agree on it before writing the implementation. Our SDK guidelines explain how we design it.
This section is for external contributors. PostHog maintainers (members of the PostHog GitHub org) agree on API shape in the PR itself, so they don't need a separate issue.
- Before you start: if you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case. Wait for a maintainer to agree on the API shape there before you implement it. Context is more useful to us than code at this stage.
- Already specified? If a published sdk-spec defines the API, that's the agreement, so you don't need an issue.
- Already have a PR open? Don't stop or rewrite it. Call out the public API change at the top of the PR description, and link or open an issue so we can discuss the shape there.
- Check first whether an existing option or hook, such as
before_send, already covers the use case. We avoid offering two ways to do the same thing. - If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.
composer api:update regenerates api/public-api.json, and CI runs composer api:check to catch an outdated snapshot. A diff in that file means your change touches public API.
The Laravel package has a separate snapshot in api/laravel-public-api.json. From the repository root:
composer install --working-dir=packages/laravel --prefer-dist --no-progress
composer api:check:laravelAfter agreeing on a Laravel API change, run composer api:update:laravel and inspect the generated diff. CI checks both snapshots. The Laravel snapshot excludes @internal classes and members; framework-required public methods do not automatically become supported customer APIs. Supported client forwarders are declared explicitly in the Laravel manager, so their signatures are tracked without exposing future core methods automatically.
Please follow the existing project conventions and include tests when you change behavior.