Setting the file. One moment.
Skill 76 · Instrument Error Tracking
Subchapter 76.21
references/php.mdMarkdown6 KBView on GitHub
AI agents: this is one page from PostHog’s docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt (opens in a new tab)
1
Required
Install the PostHog PHP SDK (opens in a new tab) via Composer:
Terminal
composer require posthog/posthog-php2
Required
Set your project token and instance address before making any calls:
PHP
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 (opens in a new tab) page in PostHog.
3
Required
Use captureException to manually capture exceptions and send them to PostHog as $exception events with full stack traces.
PHP
try {
// Your code that might throw
riskyOperation();
} catch (
4
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.
PHP
PostHog\PostHog::init(
'<ph_project_token>',
[
'host' => 'https://us.i.posthog.com',
'error_tracking' => [
'enabled' => true,
5
Recommended
By default, automatically captured errors are anonymous. Use context_provider to attach a distinctId and request metadata to every automatically captured error event.
PHP
PostHog\PostHog::init(
'<ph_project_token>',
[
'host' => 'https://us.i.posthog.com',
6
Optional
PHP
PostHog\PostHog::init(
'<ph_project_token>',
[
'host' => 'https://us.i.posthog.com',
'error_tracking' => [
'enabled'
Recommended
Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the Error Tracking (opens in a new tab) tab.
PHP
PostHog\PostHog::init(
'<ph_project_token>',
[
'host' => 'https://us.i.posthog.com',
Ask PostHog AI
HelpfulCould be better
You can pass extra properties to include with the exception event:
PHP
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.
Existing handlers are preserved
The SDK chains existing exception and error handlers instead of replacing your app’s behavior.
If distinctId is omitted, PostHog sends the event with an auto-generated ID and sets $process_person_profile to false.
| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Enables automatic error tracking handlers. Manual captureException works 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 or null | null | Callback that returns distinctId and extra event properties for automatic captures. |