Skip to content

feat(error-tracking): add PHP error tracking support#109

Open
cat-ph wants to merge 5 commits intomasterfrom
feat/php-errortracking
Open

feat(error-tracking): add PHP error tracking support#109
cat-ph wants to merge 5 commits intomasterfrom
feat/php-errortracking

Conversation

@cat-ph
Copy link
Copy Markdown

@cat-ph cat-ph commented Mar 26, 2026

Summary

Add PHP error tracking support to posthog-php.

This includes:

  • manual captureException(...) support for Throwable|string
  • opt-in automatic capture for uncaught exceptions, PHP errors, and fatal shutdown errors

Changes

  • add manual exception capture and $exception_list payload building
  • add opt-in auto registration for exception, error, and shutdown handlers
  • preserve default crash behavior when no prior exception handler exists
  • preserve first installed client as the owner of global auto-capture handlers
  • avoid double capture when warnings are promoted to ErrorException
  • capture E_USER_ERROR through the error handler path as well

Test Plan

  • php -l on changed files
  • ./vendor/bin/phpunit

Full PHPUnit passes with the repo's existing non-fatal PHPUnit issues:

  • no coverage driver
  • existing warnings/deprecations

@cat-ph cat-ph requested review from a team, ablaszkiewicz and hpouillot March 26, 2026 23:56
{
// Keep source context bounded so large local variables / generated code snippets do not push
// $exception payloads past the transport size limit.
private const MAX_CONTEXT_LINE_LENGTH = 200;
Copy link
Copy Markdown
Author

@cat-ph cat-ph Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this with the "low" default frame limit of 20 is quite an "artificial" limit to prevent #31 (the libcurl limitation of 32kb) - that might still happen, I'll try looking at that next so we can drop these afterwards, I ran into it a few times testing

Copy link
Copy Markdown

@hpouillot hpouillot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few comments, but looks good to my rusty PHP eyes 👴🏻

PostHog::init(
$_ENV['POSTHOG_PROJECT_API_KEY'],
[
'host' => $_ENV['POSTHOG_HOST'] ?? 'https://app.posthog.com',
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
'host' => $_ENV['POSTHOG_HOST'] ?? 'https://app.posthog.com',
'host' => $_ENV['POSTHOG_HOST'] ?? 'https://us.i.posthog.com',

PostHog::init('phc_xxx', [
'enable_error_tracking' => true,
'capture_uncaught_exceptions' => true,
'capture_errors' => true,
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it make sense to nest error tracking config into an error_tracking key ?

*/
private function buildExceptionList(\Throwable|string $exception): ?array
{
ExceptionCapture::configure($this->options);
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we need to reconfigure exception capture on every call ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants