fix: avoid uncaught exception recursion in error tracking

Author: cat-ph

lib/ExceptionCapture.php

@@ -30,6 +30,7 @@ class ExceptionCapture
     // Auto-capture itself can fail or trigger warnings; guard against recursively capturing
     // PostHog's own error path.
     private static bool $isCapturing = false;
+    private static bool $throwOnUnhandledInTests = false;
 
     /** @var callable|null */
     private static $previousExceptionHandler = null;
@@ -262,6 +263,12 @@ public static function resetForTests(): void
         self::$previousErrorHandler = null;
         self::$fatalErrorSignatures = [];
         self::$delegatedErrorExceptionIds = [];
+        self::$throwOnUnhandledInTests = false;
+    }
+
+    public static function enableThrowOnUnhandledForTests(): void
+    {
+        self::$throwOnUnhandledInTests = true;
     }
 
     private static function shouldCapture(): bool
@@ -555,8 +562,15 @@ private static function finishUnhandledException(\Throwable $exception): void
             return;
         }
 
-        restore_exception_handler();
-        throw $exception;
+        if (self::$throwOnUnhandledInTests) {
+            restore_exception_handler();
+            throw $exception;
+        }
+
+        // Once PHP has entered a user exception handler there is no safe way to resume the
+        // built-in uncaught-exception flow, so log the throwable and terminate explicitly.
+        error_log('Uncaught ' . $exception);
+        exit(255);
     }
 
     /**

test/ExceptionCaptureTest.php

@@ -17,6 +17,7 @@ public function setUp(): void
     {
         date_default_timezone_set("UTC");
         ExceptionCapture::resetForTests();
+        ExceptionCapture::enableThrowOnUnhandledForTests();
 
         global $errorMessages;
         $errorMessages = [];
@@ -144,21 +145,31 @@ public function testExceptionHandlerCapturesFlushesAndChainsPreviousHandler(): v
         }
     }
 
-    public function testExceptionHandlerRethrowsWhenNoPreviousHandlerExists(): void
+    public function testExceptionHandlerWithoutPreviousHandlerLogsAndExits(): void
     {
-        $this->buildClient(['error_tracking' => ['enabled' => true]]);
-        $exception = new \RuntimeException('uncaught without previous');
+        $result = $this->runStandaloneScript(<<<'PHP'
+$http = new \PostHog\Test\MockedHttpClient("app.posthog.com");
+new \PostHog\Client("key", ["debug" => true, "error_tracking" => ["enabled" => true]], $http, null, false);
 
-        try {
-            ExceptionCapture::handleException($exception);
-            $this->fail('Expected the uncaught exception to be rethrown');
-        } catch (\RuntimeException $caught) {
-            $this->assertSame($exception, $caught);
-        }
+register_shutdown_function(static function () use ($http): void {
+    global $errorMessages;
 
-        $event = $this->findExceptionEvent();
+    echo json_encode([
+        'calls' => $http->calls,
+        'error_messages' => $errorMessages,
+    ], JSON_THROW_ON_ERROR);
+});
+
+throw new \RuntimeException('uncaught without previous');
+PHP, 255, false);
+
+        $this->assertCount(1, $result['calls']);
+        $payload = json_decode($result['calls'][0]['payload'], true);
+        $event = $payload['batch'][0];
         $this->assertFalse($event['properties']['$exception_handled']);
         $this->assertSame('php_exception_handler', $event['properties']['$exception_source']);
+        $this->assertNotEmpty($result['error_messages']);
+        $this->assertStringContainsString('uncaught without previous', $result['error_messages'][0]);
     }
 
     public function testErrorHandlerCapturesNonFatalErrorsWithoutCaptureFrames(): void
@@ -609,14 +620,20 @@ private function framesContainFunction(array $frames, string $function): bool
     /**
      * @return array<string, mixed>
      */
-    private function runStandaloneScript(string $body): array
-    {
+    private function runStandaloneScript(
+        string $body,
+        int $expectedExitCode = 0,
+        bool $throwOnUnhandledInTests = true
+    ): array {
         $scriptPath = tempnam(sys_get_temp_dir(), 'posthog-error-tracking-');
         $this->assertNotFalse($scriptPath);
 
         $autoloadPath = var_export(realpath(__DIR__ . '/../vendor/autoload.php'), true);
         $errorLogMockPath = var_export(realpath(__DIR__ . '/error_log_mock.php'), true);
         $mockedHttpClientPath = var_export(realpath(__DIR__ . '/MockedHttpClient.php'), true);
+        $throwOnUnhandledBootstrap = $throwOnUnhandledInTests
+            ? "\n\\PostHog\\ExceptionCapture::enableThrowOnUnhandledForTests();"
+            : '';
 
         $script = <<<PHP
 <?php
@@ -625,6 +642,7 @@ private function runStandaloneScript(string $body): array
 require {$mockedHttpClientPath};
 
 \PostHog\ExceptionCapture::resetForTests();
+{$throwOnUnhandledBootstrap}
 {$body}
 PHP;
 
@@ -636,7 +654,7 @@ private function runStandaloneScript(string $body): array
 
             exec(PHP_BINARY . ' ' . escapeshellarg($scriptPath), $output, $exitCode);
 
-            $this->assertSame(0, $exitCode, implode("\n", $output));
+            $this->assertSame($expectedExitCode, $exitCode, implode("\n", $output));
 
             $decoded = json_decode(implode("\n", $output), true);
             $this->assertIsArray($decoded);