feat: add the Laravel runtime package

.gitattributes

@@ -6,3 +6,4 @@
 /phpcs.xml export-ignore
 /.github export-ignore
 /Makefile export-ignore
+/packages/laravel export-ignore

.github/workflows/php.yml

@@ -14,6 +14,8 @@ on:
       - "phpcs.xml"
       - "phpunit.xml"
       - "api/public-api.json"
+      - "api/laravel-public-api.json"
+      - "packages/laravel/composer.json"
       - "scripts/**"
       - ".github/workflows/php.yml"
 
@@ -70,6 +72,15 @@ jobs:
       - name: Check public API snapshot
         run: composer api:check
 
+      - name: Install Laravel dependencies
+        run: composer install --working-dir=packages/laravel --prefer-dist --no-progress
+
+      - name: Check Laravel public API snapshot
+        run: composer api:check:laravel
+
+      - name: Run Laravel tests
+        run: composer --working-dir=packages/laravel test
+
   phpunit:
     needs: detect-markdown-only
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -32,7 +32,7 @@ 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.
+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):
 
@@ -60,6 +60,15 @@ This section is for external contributors. PostHog maintainers (members of the P
 
 `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:
+
+```bash
+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.

RELEASING.md

@@ -43,6 +43,10 @@ The pending change intents determine the next version:
 
 When multiple intents are pending, the workflow uses the largest requested bump.
 
+## Composer distribution archives
+
+The root `.gitattributes` excludes `packages/laravel/` from the core Composer distribution. Laravel source stays in Git and has its own publishing flow. Tools that need the complete repository must use a Git checkout, not the core distribution archive. In particular, a whole-repository `git archive` no longer includes Laravel source or tests.
+
 ## Troubleshooting
 
 ### No releasable change intents found