Skip to content

Latest commit

 

History

History
101 lines (69 loc) · 5.27 KB

CONTRIBUTING.md

File metadata and controls

101 lines (69 loc) · 5.27 KB

Contributing

Thanks for your interest in improving the PostHog PHP SDK.

Commit signing

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.

Development setup

  1. Install PHP and Composer. Enable PHP's zlib extension for the gzip regression tests. This is a development-only dependency, not an SDK runtime requirement.

  2. Install dependencies using the same command CI uses:

    composer install --prefer-dist --no-progress

Running the example app

  1. Copy .env.example to .env and add your PostHog credentials.

  2. Run the interactive example script:

    php example.php

CI-aligned checks

Run the test command used in CI:

XDEBUG_MODE=coverage ./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --coverage-text

The 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 -v

After 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 test

Laravel development

packages/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 13

The 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 changes

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:laravel

After 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.

Pull requests

Please follow the existing project conventions and include tests when you change behavior.