Skip to content

Commit 9c03f90

Browse files
cat-phcat-ph
committed
docs(php): expand error tracking docs
1 parent de3ab05 commit 9c03f90

2 files changed

Lines changed: 128 additions & 8 deletions

File tree

‎contents/docs/error-tracking/installation/php.mdx‎

Lines changed: 104 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ Install the [PostHog PHP SDK](/docs/libraries/php) via Composer:
1717
composer require posthog/posthog-php
1818
```
1919

20-
<CalloutBox icon="IconInfo" title="Source context not yet supported" type="fyi">
20+
<CalloutBox icon="IconInfo" title="Source code context" type="fyi">
2121

22-
The PHP SDK captures stack traces with file names, line numbers, and function names, but does not yet support source context (displaying the surrounding lines of code in the error tracking UI). Symbol set uploads for PHP are not currently available.
22+
For in-app frames, the PHP SDK reads source files directly at runtime and includes surrounding lines of code when those files are readable by the process. PHP does not use symbol set uploads for this.
2323

2424
</CalloutBox>
2525

@@ -36,7 +36,7 @@ PostHog\PostHog::init(
3636
);
3737
```
3838

39-
You can find your project token and instance address in the [project settings](https://us.posthog.com/settings/project) page in PostHog.
39+
You can find your project token and instance address in the [project settings](https://app.posthog.com/settings/project) page in PostHog.
4040

4141
</Step>
4242

@@ -50,7 +50,7 @@ Use `captureException` to manually capture exceptions and send them to PostHog a
5050
try {
5151
// Your code that might throw
5252
riskyOperation();
53-
} catch (\Exception $e) {
53+
} catch (\Throwable $e) {
5454
PostHog\PostHog::captureException($e, 'user_distinct_id');
5555
}
5656
```
@@ -62,29 +62,125 @@ You can pass extra properties to include with the exception event:
6262
```php
6363
try {
6464
processOrder($orderId);
65-
} catch (\Exception $e) {
65+
} catch (\Throwable $e) {
6666
PostHog\PostHog::captureException($e, 'user_distinct_id', [
6767
'order_id' => $orderId,
6868
'environment' => 'production',
6969
]);
7070
}
7171
```
7272

73+
You can also pass a plain string if you want to send an error message without a `Throwable`.
74+
75+
</Step>
76+
77+
<Step title="Enable automatic capture (recommended)" badge="recommended">
78+
79+
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.
80+
81+
```php
82+
PostHog\PostHog::init(
83+
'<ph_project_token>',
84+
[
85+
'host' => '<ph_client_api_host>',
86+
'error_tracking' => [
87+
'enabled' => true,
88+
],
89+
]
90+
);
91+
```
92+
93+
<CalloutBox icon="IconInfo" title="Existing handlers are preserved" type="fyi">
94+
95+
The SDK chains existing exception and error handlers instead of replacing your app's behavior.
96+
97+
</CalloutBox>
98+
99+
</Step>
100+
101+
<Step title="Identify users and attach request context (recommended)" badge="recommended">
102+
103+
By default, automatically captured errors are anonymous. Use `context_provider` to attach a `distinctId` and request metadata to every automatically captured error event.
104+
105+
```php
106+
PostHog\PostHog::init(
107+
'<ph_project_token>',
108+
[
109+
'host' => '<ph_client_api_host>',
110+
'error_tracking' => [
111+
'enabled' => true,
112+
'context_provider' => static function (array $payload): array {
113+
return [
114+
'distinctId' => $_SESSION['user_id'] ?? null,
115+
'properties' => [
116+
'$current_url' => $_SERVER['REQUEST_URI'] ?? null,
117+
'$request_method' => $_SERVER['REQUEST_METHOD'] ?? null,
118+
'$exception_source' => $payload['source'] ?? null,
119+
],
120+
];
121+
},
122+
],
123+
]
124+
);
125+
```
126+
127+
If `distinctId` is omitted, PostHog sends the event with an auto-generated ID and sets `$process_person_profile` to `false`.
128+
129+
</Step>
130+
131+
<Step title="Configure error tracking options (optional)" badge="optional">
132+
133+
```php
134+
PostHog\PostHog::init(
135+
'<ph_project_token>',
136+
[
137+
'host' => '<ph_client_api_host>',
138+
'error_tracking' => [
139+
'enabled' => true,
140+
'capture_errors' => true,
141+
'excluded_exceptions' => [
142+
\InvalidArgumentException::class,
143+
],
144+
'max_frames' => 20,
145+
'context_provider' => static function (array $payload): array {
146+
return [
147+
'distinctId' => $_SESSION['user_id'] ?? null,
148+
'properties' => [],
149+
];
150+
},
151+
],
152+
]
153+
);
154+
```
155+
156+
| Option | Type | Default | Description |
157+
|---|---|---|---|
158+
| `enabled` | boolean | `false` | Enables automatic error tracking handlers. Manual `captureException` works regardless. |
159+
| `capture_errors` | boolean | `true` | When enabled, also captures PHP errors and fatal shutdown errors in addition to uncaught exceptions. |
160+
| `excluded_exceptions` | array of class strings | `[]` | Throwable classes to skip during automatic capture. |
161+
| `max_frames` | integer | `20` | Maximum number of stack frames included in `$exception_list`. |
162+
| `context_provider` | callable or `null` | `null` | Callback that returns `distinctId` and extra event properties for automatic captures. |
163+
73164
</Step>
74165

75166
<Step checkpoint title="Verify error tracking" badge="recommended">
76167

77-
Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the [Error Tracking](https://us.posthog.com/error_tracking) tab.
168+
Trigger a test exception to confirm events are being sent to PostHog. You should see them appear in the [Error Tracking](https://app.posthog.com/error_tracking) tab.
78169

79170
```php
80171
PostHog\PostHog::init(
81172
'<ph_project_token>',
82-
['host' => '<ph_client_api_host>']
173+
[
174+
'host' => '<ph_client_api_host>',
175+
'error_tracking' => [
176+
'enabled' => true,
177+
],
178+
]
83179
);
84180

85181
try {
86182
throw new \Exception('Test exception from PHP');
87-
} catch (\Exception $e) {
183+
} catch (\Throwable $e) {
88184
PostHog\PostHog::captureException($e, 'test_user');
89185
}
90186
```

‎contents/docs/libraries/php/index.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ features:
1010
userIdentification: true
1111
featureFlags: true
1212
groupAnalytics: true
13+
errorTracking: true
1314
surveys: false
1415
llmAnalytics: false
1516
---
@@ -142,6 +143,28 @@ PostHog::groupIdentify([
142143

143144
The `name` is a special property which is used in the PostHog UI for the name of the group. If you don't specify a `name` property, the group ID will be used instead.
144145

146+
## Error tracking
147+
148+
The PHP SDK supports both manual exception capture and opt-in automatic error tracking.
149+
150+
To automatically capture uncaught exceptions, PHP errors, and fatal shutdown errors, enable `error_tracking` when initializing the client:
151+
152+
```php
153+
PostHog::init(
154+
'<ph_project_token>',
155+
[
156+
'host' => '<ph_client_api_host>',
157+
'error_tracking' => [
158+
'enabled' => true,
159+
],
160+
],
161+
);
162+
```
163+
164+
You can also call `PostHog::captureException()` directly for manual capture. When source files are readable at runtime, PostHog includes surrounding source lines for in-app stack frames automatically.
165+
166+
For the full setup guide, including `context_provider`, excluded exceptions, and verification steps, see the [PHP error tracking installation docs](/docs/error-tracking/installation/php).
167+
145168
## Config options
146169

147170
When calling `PostHog::init`, there are various configuration options you can set apart from the host. Pass them into your client initialisation like so:
@@ -170,6 +193,7 @@ All possible options below:
170193
| `maximum_backoff_duration`<br/><br/>**Type:** Integer<br/>**Default:** `10000` | Request retry backoff. Retries will stop after this duration is hit |
171194
| `consumer`<br/><br/>**Type:** String<br/>**Default:** `lib_curl` | One of `socket`, `file`, `lib_curl`, and `fork_curl`. Determines what transport option to use for analytics capture. [More details here](https://github.com/PostHog/posthog-php/blob/master/lib/Consumer/File.php) |
172195
| `debug`<br/><br/>**Type:** Boolean<br/>**Default:** `false` | Output debug logs or not |
196+
| `error_tracking`<br/><br/>**Type:** Array<br/>**Default:** `[]` | Enables automatic error tracking and related options such as `context_provider`, `excluded_exceptions`, and `max_frames`. [See the setup guide](/docs/error-tracking/installation/php). |
173197

174198
## Debug mode
175199

0 commit comments

Comments
 (0)