Skip to content

Commit 3972672

Browse files
inkeep[bot]cat-ph
inkeep[bot]
and
cat-ph
authored
docs: Add PHP Error Tracking installation page (#16197)
* Add PHP Error Tracking installation docs * Add PHP to error tracking installation navigation * docs(php): expand error tracking docs --------- Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com> Co-authored-by: Catalin Irimie <catalin.i@posthog.com>
1 parent 98eb337 commit 3972672

3 files changed

Lines changed: 212 additions & 0 deletions

File tree

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

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: PHP Error Tracking installation
3+
platformLogo: php
4+
showStepsToc: true
5+
---
6+
7+
import { Steps, Step } from "components/Docs/Steps";
8+
import { CalloutBox } from "components/Docs/CalloutBox";
9+
10+
<Steps>
11+
12+
<Step title="Install the PHP SDK" badge="required">
13+
14+
Install the [PostHog PHP SDK](/docs/libraries/php) via Composer:
15+
16+
```bash
17+
composer require posthog/posthog-php
18+
```
19+
20+
</Step>
21+
22+
<Step title="Initialize the client" badge="required">
23+
24+
Set your project token and instance address before making any calls:
25+
26+
```php
27+
PostHog\PostHog::init(
28+
'<ph_project_token>',
29+
['host' => '<ph_client_api_host>']
30+
);
31+
```
32+
33+
You can find your project token and instance address in the [project settings](https://app.posthog.com/settings/project) page in PostHog.
34+
35+
</Step>
36+
37+
<Step title="Capture exceptions" badge="required">
38+
39+
Use `captureException` to manually capture exceptions and send them to PostHog as `$exception` events with full stack traces.
40+
41+
### Basic usage
42+
43+
```php
44+
try {
45+
// Your code that might throw
46+
riskyOperation();
47+
} catch (\Throwable $e) {
48+
PostHog\PostHog::captureException($e, 'user_distinct_id');
49+
}
50+
```
51+
52+
### With additional properties
53+
54+
You can pass extra properties to include with the exception event:
55+
56+
```php
57+
try {
58+
processOrder($orderId);
59+
} catch (\Throwable $e) {
60+
PostHog\PostHog::captureException($e, 'user_distinct_id', [
61+
'order_id' => $orderId,
62+
'environment' => 'production',
63+
]);
64+
}
65+
```
66+
67+
You can also pass a plain string if you want to send an error message without a `Throwable`.
68+
69+
</Step>
70+
71+
<Step title="Enable automatic capture" badge="recommended">
72+
73+
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.
74+
75+
```php
76+
PostHog\PostHog::init(
77+
'<ph_project_token>',
78+
[
79+
'host' => '<ph_client_api_host>',
80+
'error_tracking' => [
81+
'enabled' => true,
82+
],
83+
]
84+
);
85+
```
86+
87+
<CalloutBox icon="IconInfo" title="Existing handlers are preserved" type="fyi">
88+
89+
The SDK chains existing exception and error handlers instead of replacing your app's behavior.
90+
91+
</CalloutBox>
92+
93+
</Step>
94+
95+
<Step title="Identify users and attach request context" badge="recommended">
96+
97+
By default, automatically captured errors are anonymous. Use `context_provider` to attach a `distinctId` and request metadata to every automatically captured error event.
98+
99+
```php
100+
PostHog\PostHog::init(
101+
'<ph_project_token>',
102+
[
103+
'host' => '<ph_client_api_host>',
104+
'error_tracking' => [
105+
'enabled' => true,
106+
'context_provider' => static function (array $payload): array {
107+
return [
108+
'distinctId' => $_SESSION['user_id'] ?? null,
109+
'properties' => [
110+
'$current_url' => $_SERVER['REQUEST_URI'] ?? null,
111+
'$request_method' => $_SERVER['REQUEST_METHOD'] ?? null,
112+
'$exception_source' => $payload['source'] ?? null,
113+
],
114+
];
115+
},
116+
],
117+
]
118+
);
119+
```
120+
121+
If `distinctId` is omitted, PostHog sends the event with an auto-generated ID and sets `$process_person_profile` to `false`.
122+
123+
</Step>
124+
125+
<Step title="Configure error tracking options" badge="optional">
126+
127+
```php
128+
PostHog\PostHog::init(
129+
'<ph_project_token>',
130+
[
131+
'host' => '<ph_client_api_host>',
132+
'error_tracking' => [
133+
'enabled' => true,
134+
'capture_errors' => true,
135+
'excluded_exceptions' => [
136+
\InvalidArgumentException::class,
137+
],
138+
'max_frames' => 20,
139+
'context_provider' => static function (array $payload): array {
140+
return [
141+
'distinctId' => $_SESSION['user_id'] ?? null,
142+
'properties' => [],
143+
];
144+
},
145+
],
146+
]
147+
);
148+
```
149+
150+
| Option | Type | Default | Description |
151+
|---|---|---|---|
152+
| `enabled` | boolean | `false` | Enables automatic error tracking handlers. Manual `captureException` works regardless. |
153+
| `capture_errors` | boolean | `true` | When enabled, also captures PHP errors and fatal shutdown errors in addition to uncaught exceptions. |
154+
| `excluded_exceptions` | array of class strings | `[]` | Throwable classes to skip during automatic capture. |
155+
| `max_frames` | integer | `20` | Maximum number of stack frames included in `$exception_list`. |
156+
| `context_provider` | callable or `null` | `null` | Callback that returns `distinctId` and extra event properties for automatic captures. |
157+
158+
</Step>
159+
160+
<Step checkpoint title="Verify error tracking" badge="recommended">
161+
162+
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.
163+
164+
```php
165+
PostHog\PostHog::init(
166+
'<ph_project_token>',
167+
[
168+
'host' => '<ph_client_api_host>',
169+
'error_tracking' => [
170+
'enabled' => true,
171+
],
172+
]
173+
);
174+
175+
try {
176+
throw new \Exception('Test exception from PHP');
177+
} catch (\Throwable $e) {
178+
PostHog\PostHog::captureException($e, 'test_user');
179+
}
180+
```
181+
182+
</Step>
183+
184+
</Steps>

‎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

‎src/navs/index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4560,6 +4560,10 @@ export const docsMenu = {
45604560
name: 'Go',
45614561
url: '/docs/error-tracking/installation/go',
45624562
},
4563+
{
4564+
name: 'PHP',
4565+
url: '/docs/error-tracking/installation/php',
4566+
},
45634567
{
45644568
name: 'iOS',
45654569
url: '/docs/error-tracking/installation/ios',

0 commit comments

Comments
 (0)