references/php.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
PHP Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/php
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install the PHP SDK
- Initialize the client
- Capture exceptions
- Enable automatic capture
- Identify users and attach request context
- Configure error tracking options
- Verify error tracking
- Link releases
-
1
Install the PHP SDK
Required
Install the PostHog PHP SDK via Composer:
composer require posthog/posthog-php -
2
Initialize the client
Required
Set your project token and instance address before making any calls:
PostHog\PostHog::init( '<ph_project_token>', ['host' => 'https://us.i.posthog.com'] );You can find your project token and instance address in the project settings page in PostHog.
-
3
Capture exceptions
Required
Use
captureExceptionto manually capture exceptions and send them to PostHog as$exceptionevents with full stack traces.Basic usage
try { // Your code that might throw riskyOperation(); } catch (\Throwable $e) { PostHog\PostHog::captureException($e, 'user_distinct_id'); }With additional properties
You can pass extra properties to include with the exception event:
try { processOrder($orderId); } catch (\Throwable $e) { PostHog\PostHog::captureException($e, 'user_distinct_id', [ 'order_id' => $orderId, 'environment' => 'production', ]); }You can also pass a plain string if you want to send an error message without a
Throwable. -
4
Enable automatic capture
Recommended
Automatic capture is opt-in for PHP. When enabled, the SDK installs handlers for uncaught exceptions. With the default
capture_errors: true, it also captures PHP errors and fatal shutdown errors.PostHog\PostHog::init( '<ph_project_token>', [ 'host' => 'https://us.i.posthog.com', 'error_tracking' => [ 'enabled' => true, ], ] );Existing handlers are preserved
The SDK chains existing exception and error handlers instead of replacing your app's behavior.
-
5
Identify users and attach request context
Recommended
By default, automatically captured errors are anonymous. Use
context_providerto attach adistinctIdand request metadata to every automatically captured error event.PostHog\PostHog::init( '<ph_project_token>', [ 'host' => 'https://us.i.posthog.com', 'error_tracking' => [ 'enabled' => true, 'context_provider' => static function (array $payload): array { return [ 'distinctId' => $_SESSION['user_id'] ?? null, 'properties' => [ '$current_url' => $_SERVER['REQUEST_URI'] ?? null, '$request_method' => $_SERVER['REQUEST_METHOD'] ?? null, '$exception_source' => $payload['source'] ?? null, ], ]; }, ], ] );If
distinctIdis omitted, PostHog sends the event with an auto-generated ID and sets$process_person_profiletofalse. -
6
Configure error tracking options
Optional
PostHog\PostHog::init( '<ph_project_token>', [ 'host' => 'https://us.i.posthog.com', 'error_tracking' => [ 'enabled' => true, 'capture_errors' => true, 'excluded_exceptions' => [ \InvalidArgumentException::class, ], 'max_frames' => 20, 'context_provider' => static function (array $payload): array { return [ 'distinctId' => $_SESSION['user_id'] ?? null, 'properties' => [], ]; }, ], ] );| Option | Type | Default | Description | | --- | --- | --- | --- | |
enabled| boolean |false| Enables automatic error tracking handlers. ManualcaptureExceptionworks regardless. | |capture_errors| boolean |true| When enabled, also captures PHP errors and fatal shutdown errors in addition to uncaught exceptions. | |excluded_exceptions| array of class strings |[]| Throwable classes to skip during automatic capture. | |max_frames| integer |20| Maximum number of stack frames included in$exception_list. | |context_provider| callable ornull|null| Callback that returnsdistinctIdand extra event properties for automatic captures. | -
Verify error tracking
Recommended
Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the Error Tracking tab.
PostHog\PostHog::init( '<ph_project_token>', [ 'host' => 'https://us.i.posthog.com', 'error_tracking' => [ 'enabled' => true, ], ] ); try { throw new \Exception('Test exception from PHP'); } catch (\Throwable $e) { PostHog\PostHog::captureException($e, 'test_user'); } -
7
Link releases
Optional
Great, you're capturing exceptions! To see which release each exception comes from, give your app the release ID when you deploy.