PostHog · hpouillot · Aug 26, 2026
@@ -0,0 +1,5 @@
+---
+'posthog-php': minor
+---
+
+Standardize exception capture metadata, including severity, capture source, mechanism semantics, deterministic cause linkage, and reserved property ownership.
@@ -556,11 +556,17 @@ public function captureException(
             return false;
         }
 
+        $reservedExceptionProperties = array_flip([
+            '$exception_list', '$exception_level', '$exception_source', '$debug_images',
+            '$exception_handled', '$exception_types', '$exception_values', '$exception_sources',
+            '$exception_functions', '$exception_fingerprint_version', '$exception_fingerprint_record',
+            '$exception_issue_id', '$exception_release', '$cymbal_errors',
+        ]);
         $properties = array_merge(
-            $additionalProperties,
+            array_diff_key($additionalProperties, $reservedExceptionProperties),
             [
                 '$exception_list' => $exceptionList,
-                '$exception_handled' => ExceptionPayloadBuilder::getPrimaryHandled($exceptionList),
+                '$exception_level' => 'error',
             ]
         );
 

@@ -180,8 +180,8 @@ public static function handleError(
                     $exception,
                     $errno,
                     'error_handler',
-                    'php_error_handler',
-                    ['type' => 'auto.error_handler', 'handled' => false],
+                    'php.error_handler',
+                    ['type' => 'error_handler', 'handled' => false, 'synthetic' => true],
                     [$exceptionEntry]
                 );
 
@@ -201,8 +201,8 @@ public static function handleError(
                 $exception,
                 $errno,
                 'error_handler',
-                'php_error_handler',
-                ['type' => 'auto.error_handler', 'handled' => $handled],
+                'php.error_handler',
+                ['type' => 'error_handler', 'handled' => $handled, 'synthetic' => true],
                 [$exceptionEntry]
             );
 
@@ -269,8 +269,8 @@ public static function handleShutdown(?array $lastError = null): void
             $exception,
             $severity,
             'shutdown_handler',
-            'php_shutdown_handler',
-            ['type' => 'auto.shutdown_handler', 'handled' => false],
+            'php.shutdown_handler',
+            ['type' => 'crash_reporter', 'handled' => false, 'synthetic' => true],
             [$exceptionEntry]
         );
 
@@ -369,11 +369,19 @@ private static function captureUncaughtException(\Throwable $exception): void
         $maxFrames = self::$options['max_frames'] ?? 20;
         $exceptionList = ExceptionPayloadBuilder::buildExceptionList($exception, $maxFrames);
         $exceptionList = ExceptionPayloadBuilder::overridePrimaryMechanism($exceptionList, [
-            'type' => 'auto.exception_handler',
+            'type' => 'onuncaughtexception',
             'handled' => false,
+            'synthetic' => false,
         ]);
 
-        self::sendExceptionEvent($exception, 'exception_handler', 'php_exception_handler', $exceptionList);
+        self::sendExceptionEvent(
+            $exception,
+            'exception_handler',
+            'php.exception_handler',
+            $exceptionList,
+            null,
+            'fatal'
+        );
     }
 
     /**
@@ -388,7 +396,14 @@ private static function captureErrorException(
         array $exceptionList
     ): void {
         $exceptionList = ExceptionPayloadBuilder::overridePrimaryMechanism($exceptionList, $mechanism);
-        self::sendExceptionEvent($exception, $contextSource, $eventSource, $exceptionList, $severity);
+        self::sendExceptionEvent(
+            $exception,
+            $contextSource,
+            $eventSource,
+            $exceptionList,
+            $severity,
+            self::levelForSeverity($severity, ExceptionPayloadBuilder::getPrimaryHandled($exceptionList))
+        );
     }
 
     /**
@@ -401,7 +416,8 @@ private static function sendExceptionEvent(
         string $contextSource,
         string $eventSource,
         array $exceptionList,
-        ?int $severity = null
+        ?int $severity = null,
+        string $level = 'error'
     ): void {
         if (self::$client === null || self::$isCapturing) {
             return;
@@ -421,15 +437,21 @@ private static function sendExceptionEvent(
 
             $properties = [
                 '$exception_list' => $exceptionList,
-                '$exception_handled' => ExceptionPayloadBuilder::getPrimaryHandled($exceptionList),
                 '$exception_source' => $eventSource,
+                '$exception_level' => $level,
             ];
 
             if ($severity !== null) {
                 $properties['$php_error_severity'] = $severity;
             }
 
-            $properties = array_merge($providerContext['properties'], $properties);
+            $reserved = array_flip([
+                '$exception_list', '$exception_level', '$exception_source', '$debug_images',
+                '$exception_handled', '$exception_types', '$exception_values', '$exception_sources',
+                '$exception_functions', '$exception_fingerprint_version', '$exception_fingerprint_record',
+                '$exception_issue_id', '$exception_release', '$cymbal_errors',
+            ]);
+            $properties = array_merge(array_diff_key($providerContext['properties'], $reserved), $properties);
 
             $distinctId = $providerContext['distinctId'];
             if ($distinctId === null) {
@@ -449,6 +471,23 @@ private static function sendExceptionEvent(
         }
     }
 
+    private static function levelForSeverity(int $severity, bool $handled): string
+    {
+        if (!$handled && in_array($severity, self::SHUTDOWN_FATAL_ERROR_TYPES, true)) {
+            return 'fatal';
+        }
+        if (in_array($severity, [E_WARNING, E_USER_WARNING, E_CORE_WARNING, E_COMPILE_WARNING], true)) {
+            return 'warning';
+        }
+        if (in_array($severity, [E_NOTICE, E_USER_NOTICE, E_STRICT], true)) {
+            return 'info';
+        }
+        if (in_array($severity, [E_DEPRECATED, E_USER_DEPRECATED], true)) {
+            return 'warning';
+        }
+        return 'error';
+    }
+
     /**
      * @param array<int, array<string, mixed>> $trace
      * @return array<int, array<string, mixed>>

@@ -26,19 +26,27 @@ public static function buildExceptionList(
         int $maxFrames = self::DEFAULT_MAX_FRAMES
     ): array {
         if (is_string($exception)) {
-            return [self::buildSingleException('Error', $exception, null, $maxFrames)];
+            return self::finalizeExceptionList([
+                self::buildSingleException('Error', $exception, null, $maxFrames, true),
+            ]);
         }
 
         if ($exception instanceof \Throwable) {
             $chain = [];
             $current = $exception;
 
-            while ($current !== null) {
+            $seen = [];
+            while ($current !== null && count($chain) < 50) {
+                $id = spl_object_id($current);
+                if (isset($seen[$id])) {
+                    break;
+                }
+                $seen[$id] = true;
                 $chain[] = self::buildThrowableException($current, $maxFrames);
                 $current = $current->getPrevious();
             }
 
-            return $chain;
+            return self::finalizeExceptionList($chain);
         }
 
         return [];
@@ -61,7 +69,8 @@ public static function buildFromTrace(
             get_class($exception),
             $exception->getMessage(),
             $trace,
-            $maxFrames
+            $maxFrames,
+            false
         );
     }
 
@@ -91,7 +100,7 @@ public static function buildFromLocation(
             ]];
         }
 
-        return self::buildSingleException($type, $message, $trace, $maxFrames);
+        return self::buildSingleException($type, $message, $trace, $maxFrames, true);
     }
 
     /**
@@ -107,7 +116,11 @@ public static function overridePrimaryMechanism(array $exceptionList, array $mec
             return $exceptionList;
         }
 
-        $exceptionList[0]['mechanism'] = array_merge($exceptionList[0]['mechanism'] ?? [], $mechanism);
+        $exceptionList = self::finalizeExceptionList($exceptionList);
+        $exceptionList[0]['mechanism'] = array_merge(
+            $exceptionList[0]['mechanism'] ?? [],
+            self::validMechanism($mechanism)
+        );
 
         return $exceptionList;
     }
@@ -129,7 +142,8 @@ private static function buildThrowableException(\Throwable $exception, int $maxF
             get_class($exception),
             $exception->getMessage(),
             self::normalizeThrowableTrace($exception),
-            $maxFrames
+            $maxFrames,
+            false
         );
     }
 
@@ -201,19 +215,73 @@ private static function isDeclarationLineForFirstFrame(\Throwable $exception, ar
         }
     }
 
-    private static function buildSingleException(string $type, string $message, ?array $trace, int $maxFrames): array
+    private static function buildSingleException(
+        string $type,
+        string $message,
+        ?array $trace,
+        int $maxFrames,
+        bool $synthetic
+    ): array
     {
         return [
             'type'      => $type,
             'value'     => $message,
             'mechanism' => [
                 'type'    => 'generic',
                 'handled' => true,
+                'synthetic' => $synthetic,
             ],
             'stacktrace' => self::buildStacktrace($trace, $maxFrames),
         ];
     }
 
+    /** @param array<int, array<string, mixed>> $exceptionList */
+    private static function finalizeExceptionList(array $exceptionList): array
+    {
+        $exceptionList = array_slice($exceptionList, 0, 50);
+        foreach ($exceptionList as $index => &$entry) {
+            $mechanism = self::validMechanism($entry['mechanism'] ?? []);
+            $mechanism['exception_id'] = $index;
+            if ($index === 0) {
+                unset($mechanism['parent_id'], $mechanism['source']);
+                $mechanism['type'] = $mechanism['type'] ?? 'generic';
+                $mechanism['handled'] = $mechanism['handled'] ?? true;
+            } else {
+                $mechanism['type'] = 'chained';
+                $mechanism['source'] = 'cause';
+                $mechanism['parent_id'] = $index - 1;
+                unset($mechanism['handled']);
+            }
+            $entry['mechanism'] = $mechanism;
+        }
+        unset($entry);
+        return $exceptionList;
+    }
+
+    /** @param mixed $mechanism */
+    private static function validMechanism($mechanism): array
+    {
+        if (!is_array($mechanism)) {
+            return [];
+        }
+        $result = array_diff_key($mechanism, array_flip([
+            'type', 'handled', 'source', 'synthetic', 'exception_id', 'parent_id',
+        ]));
+        if (is_string($mechanism['type'] ?? null) && $mechanism['type'] !== '') {
+            $result['type'] = $mechanism['type'];
+        }
+        if (is_bool($mechanism['handled'] ?? null)) {
+            $result['handled'] = $mechanism['handled'];
+        }
+        if (is_string($mechanism['source'] ?? null) && $mechanism['source'] !== '') {
+            $result['source'] = $mechanism['source'];
+        }
+        if (is_bool($mechanism['synthetic'] ?? null)) {
+            $result['synthetic'] = $mechanism['synthetic'];
+        }
+        return $result;
+    }
+
     private static function buildStacktrace(?array $trace, int $maxFrames): ?array
     {
         if (empty($trace)) {