PostHog · marandaneto · Jun 18, 2026 · Jun 18, 2026
@@ -0,0 +1,5 @@
+---
+"posthog-php": patch
+---
+
+Stop sending deprecated, backend-ignored top-level batch event fields. SDK metadata now uses canonical event properties (`$lib`, `$lib_version`, `$lib_consumer`), while legacy top-level SDK metadata values remain supported as fallbacks when canonical values are absent. `type` is ignored, and `send_feature_flags` remains a deprecated capture option but is stripped from the outgoing `/batch/` payload.
@@ -3227,6 +3227,10 @@
                     "type": "string",
                     "value": "POSTHOG_HOST"
                 },
+                "LIBRARY": {
+                    "type": "string",
+                    "value": "posthog-php"
+                },
                 "VERSION": {
                     "type": "string",
                     "value": "<version>"

@@ -209,7 +209,11 @@ public function __destruct()
      *     send_feature_flags?: bool,
      *     sendFeatureFlags?: bool
      * } $message Event payload. `send_feature_flags` and `sendFeatureFlags` are deprecated; pass
-     *     a `flags` snapshot from evaluateFlags() instead.
+     *     a `flags` snapshot from evaluateFlags() instead. Deprecated top-level batch metadata is
+     *     stripped before sending: use `event` instead of `type`, `properties['$lib']` instead of
+     *     `library`, `properties['$lib_version']` instead of `library_version`, and
+     *     `properties['$lib_consumer']` instead of `library_consumer`. Legacy top-level SDK metadata
+     *     values are still used as fallbacks when the canonical property is absent; `type` is ignored.
      * @return bool Whether the capture call succeeded.
      */
     public function capture(array $message)
@@ -222,7 +226,6 @@ public function capture(array $message)
             $message = $this->applyCaptureContext($message, $usedGeneratedPersonlessDistinctId);
         }
         $message = $this->message($message);
-        $message["type"] = "capture";
 
         if (array_key_exists('$groups', $message)) {
             $message["properties"]['$groups'] = $message['$groups'];
@@ -277,6 +280,7 @@ public function capture(array $message)
             }
         }
 
+        unset($message["send_feature_flags"]);
 
         return $this->consumer->capture($message);
     }
@@ -335,8 +339,8 @@ public function identify(array $message)
         }
 
         $message = $this->message($message);
-        $message["type"] = "identify";
         $message["event"] = '$identify';
+        unset($message["send_feature_flags"]);
 
         return $this->consumer->identify($message);
     }
@@ -1185,7 +1189,7 @@ public function localFlags(): HttpResponse
 
         $headers = [
             // Send user agent in the form of {library_name}/{library_version} as per RFC 7231.
-            "User-Agent: posthog-php/" . PostHog::VERSION,
+            "User-Agent: " . PostHog::LIBRARY . "/" . PostHog::VERSION,
             "Authorization: Bearer " . $this->personalAPIKey
         ];
 
@@ -1352,7 +1356,7 @@ private function requestFlags(
             json_encode($payload),
             [
                 // Send user agent in the form of {library_name}/{library_version} as per RFC 7231.
-                "User-Agent: posthog-php/" . PostHog::VERSION,
+                "User-Agent: " . PostHog::LIBRARY . "/" . PostHog::VERSION,
             ],
             [
                 "shouldRetry" => false,
@@ -1420,8 +1424,8 @@ private function emptyFlagsResponse(): array
     public function alias(array $message)
     {
         $message = $this->message($message);
-        $message["type"] = "alias";
         $message["event"] = '$create_alias';
+        unset($message["send_feature_flags"]);
 
         $message['properties']['distinct_id'] = $message['distinct_id'];
         $message['properties']['alias'] = $message['alias'];
@@ -1651,13 +1655,29 @@ private function message($msg)
             $msg["properties"] = array();
         }
 
-        $msg["library"] = 'posthog-php';
-        $msg["library_version"] = PostHog::VERSION;
-        $msg["library_consumer"] = $this->consumer->getConsumer();
+        $legacyLibrary = $msg["library"] ?? null;
+        $legacyLibraryVersion = $msg["library_version"] ?? null;
+        $legacyLibraryConsumer = $msg["library_consumer"] ?? null;
 
-        $msg["properties"]['$lib'] = 'posthog-php';
-        $msg["properties"]['$lib_version'] = PostHog::VERSION;
-        $msg["properties"]['$lib_consumer'] = $this->consumer->getConsumer();
+        unset($msg["type"], $msg["library"], $msg["library_version"], $msg["library_consumer"]);
+
+        if (!array_key_exists('$lib', $msg["properties"])) {
+            $msg["properties"]['$lib'] = is_scalar($legacyLibrary) && (string) $legacyLibrary !== ''
+                ? (string) $legacyLibrary
+                : PostHog::LIBRARY;
+        }
+
+        if (!array_key_exists('$lib_version', $msg["properties"])) {
+            $msg["properties"]['$lib_version'] = is_scalar($legacyLibraryVersion) && (string) $legacyLibraryVersion !== ''
+                ? (string) $legacyLibraryVersion
+                : PostHog::VERSION;
+        }
+
+        if (!array_key_exists('$lib_consumer', $msg["properties"])) {
+            $msg["properties"]['$lib_consumer'] = is_scalar($legacyLibraryConsumer) && (string) $legacyLibraryConsumer !== ''
+                ? (string) $legacyLibraryConsumer
+                : $this->consumer->getConsumer();
+        }
 
         // When running as a server SDK (the default), tag events as server-side so
         // PostHog does not attribute the host machine's device/OS to the event.

@@ -86,9 +86,7 @@ public function flushBatch($messages)
         }
 
         // Send user agent in the form of {library_name}/{library_version} as per RFC 7231.
-        $libName = $messages[0]['library'];
-        $libVersion = $messages[0]['library_version'];
-        $cmd .= " -H 'User-Agent: $libName/$libVersion'";
+        $cmd .= " -H 'User-Agent: " . $this->userAgent() . "'";
 
         if (!$this->debug()) {
             $cmd .= " > /dev/null 2>&1 &";

@@ -78,7 +78,7 @@ public function flushBatch($messages)
             $payload,
             [
                 // Send user agent in the form of {library_name}/{library_version} as per RFC 7231.
-                "User-Agent: {$messages[0]['library']}/{$messages[0]['library_version']}",
+                "User-Agent: {$this->userAgent()}",
             ],
             [
                 'shouldVerify' => $shouldVerify,

@@ -192,10 +192,7 @@ private function createBody($host, $content)
         $req .= "Accept: application/json\r\n";
 
         // Send user agent in the form of {library_name}/{library_version} as per RFC 7231.
-        $content_json = json_decode($content, true);
-        $libName = $content_json['batch'][0]['library'];
-        $libVersion = $content_json['batch'][0]['library_version'];
-        $req .= "User-Agent: $libName/$libVersion\r\n";
+        $req .= "User-Agent: " . $this->userAgent() . "\r\n";
 
         // Compress content if compress_request is true
         if ($this->compress_request) {

@@ -9,6 +9,7 @@
  */
 class PostHog
 {
+    public const LIBRARY = 'posthog-php';
     public const VERSION = '4.6.0';
     public const ENV_API_KEY = "POSTHOG_API_KEY";
     public const ENV_HOST = "POSTHOG_HOST";
@@ -124,7 +125,11 @@ public static function captureException(
      *     send_feature_flags?: bool,
      *     sendFeatureFlags?: bool
      * } $message Event payload. `send_feature_flags` and `sendFeatureFlags` are deprecated; pass
-     *     a `flags` snapshot from evaluateFlags() instead.
+     *     a `flags` snapshot from evaluateFlags() instead. Deprecated top-level batch metadata is
+     *     stripped before sending: use `event` instead of `type`, `properties['$lib']` instead of
+     *     `library`, `properties['$lib_version']` instead of `library_version`, and
+     *     `properties['$lib_consumer']` instead of `library_consumer`. Legacy top-level SDK metadata
+     *     values are still used as fallbacks when the canonical property is absent; `type` is ignored.
      * @return bool Whether the capture call succeeded.
      * @throws Exception
      */
@@ -147,7 +152,6 @@ public static function capture(array $message)
     public static function identify(array $message)
     {
         self::checkClient();
-        $message["type"] = "identify";
         self::validate($message, "identify");
 
         return self::$client->identify($message);

@@ -156,4 +156,14 @@ protected function payload($batch)
             "api_key" => $this->apiKey,
         );
     }
+
+    /**
+     * Get the SDK user agent.
+     *
+     * @return string User agent in the form of {library_name}/{library_version}.
+     */
+    protected function userAgent(): string
+    {
+        return PostHog::LIBRARY . "/" . PostHog::VERSION;
+    }
 }
@@ -71,7 +71,6 @@
 foreach ($lines as $line) {
   if (!trim($line)) continue;
   $payload = json_decode($line, true);
-  $type = $payload["type"];
   $ret = call_user_func_array(array("PostHog\\PostHog", "raw"), array($payload));
   if ($ret) $successful++;
   $total++;

@@ -44,7 +44,7 @@ public function testCapture(): void
                 )
             )
         );
-        $this->checkWritten("capture");
+        $this->checkWritten("File PHP Event - Microtime");
     }
 
     public function testIdentify(): void
@@ -61,7 +61,7 @@ public function testIdentify(): void
                 )
             )
         );
-        $this->checkWritten("identify");
+        $this->checkWritten('$identify');
     }
 
     public function testAlias(): void
@@ -75,7 +75,7 @@ public function testAlias(): void
             )
         );
 
-        $this->checkWritten("alias");
+        $this->checkWritten('$create_alias');
     }
 
     public function testSend(): void
@@ -108,14 +108,15 @@ public function testProductionProblems(): void
         self::assertFalse($captured);
     }
 
-    private function checkWritten($type): void
+    private function checkWritten($event): void
     {
         exec("wc -l " . $this->filename, $output);
         $out = trim($output[0]);
         self::assertSame($out, "1 " . $this->filename);
         $str = file_get_contents($this->filename);
         $json = json_decode(trim($str));
-        self::assertSame($type, $json->type);
+        self::assertObjectNotHasProperty('type', $json);
+        self::assertSame($event, $json->event);
         unlink($this->filename);
     }
 

@@ -513,14 +513,14 @@ function recurseForPayloadLimit(int \$n): void
             $payload = json_encode([
                 'batch' => [[
                     'event' => '$exception',
-                    'properties' => ['$exception_list' => $exceptionList],
+                    'properties' => [
+                        '$exception_list' => $exceptionList,
+                        '$lib' => 'posthog-php',
+                        '$lib_version' => PostHog::VERSION,
+                        '$lib_consumer' => 'LibCurl',
+                    ],
                     'distinct_id' => 'user-123',
-                    'library' => 'posthog-php',
-                    'library_version' => PostHog::VERSION,
-                    'library_consumer' => 'LibCurl',
-                    'groups' => [],
                     'timestamp' => date('c'),
-                    'type' => 'capture',
                 ]],
                 'api_key' => self::FAKE_API_KEY,
             ]);

@@ -1453,7 +1453,7 @@ public function testSimpleFlag()
                     ),
                     1 => array(
                         "path" => "/batch/",
-                        'payload' => '{"batch":[{"properties":{"$feature_flag":"simple-flag","$feature_flag_response":true,"$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"some-distinct-id","event":"$feature_flag_called","$groups":[],"library":"posthog-php","library_version":"' . PostHog::VERSION . '","library_consumer":"LibCurl","groups":[],"timestamp":"2022-05-01T00:00:00+00:00","type":"capture"}],"api_key":"random_key"}',
+                        'payload' => '{"batch":[{"properties":{"$feature_flag":"simple-flag","$feature_flag_response":true,"$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"some-distinct-id","event":"$feature_flag_called","$groups":[],"groups":[],"timestamp":"2022-05-01T00:00:00+00:00"}],"api_key":"random_key"}',
                         "extraHeaders" => array(0 => 'User-Agent: posthog-php/' . PostHog::VERSION),
                         "requestOptions" => array('shouldVerify' => true),
                     ),

@@ -97,7 +97,7 @@ public function testIsFeatureEnabledCapturesFeatureFlagCalledEventWithAdditional
                     ),
                 1 => array(
                     "path" => "/batch/",
-                    "payload" => '{"batch":[{"properties":{"$feature_flag":"simple-test","$feature_flag_response":true,"$feature_flag_request_id":"98487c8a-287a-4451-a085-299cd76228dd","$feature_flag_id":6,"$feature_flag_version":1,"$feature_flag_reason":"Matched condition set 1","$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"user-id","event":"$feature_flag_called","$groups":[],"library":"posthog-php","library_version":"' . PostHog::VERSION . '","library_consumer":"LibCurl","groups":[],"timestamp":"2022-05-01T00:00:00+00:00","type":"capture"}],"api_key":"random_key"}',
+                    "payload" => '{"batch":[{"properties":{"$feature_flag":"simple-test","$feature_flag_response":true,"$feature_flag_request_id":"98487c8a-287a-4451-a085-299cd76228dd","$feature_flag_id":6,"$feature_flag_version":1,"$feature_flag_reason":"Matched condition set 1","$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"user-id","event":"$feature_flag_called","$groups":[],"groups":[],"timestamp":"2022-05-01T00:00:00+00:00"}],"api_key":"random_key"}',
                     "extraHeaders" => array(0 => 'User-Agent: posthog-php/' . PostHog::VERSION),
                     "requestOptions" => array('shouldVerify' => true),
                     ),
@@ -196,7 +196,7 @@ public function testGetFeatureFlagCapturesFeatureFlagCalledEventWithAdditionalMe
                 ),
                 1 => array(
                     "path" => "/batch/",
-                    "payload" => '{"batch":[{"properties":{"$feature_flag":"multivariate-test","$feature_flag_response":"variant-value","$feature_flag_request_id":"98487c8a-287a-4451-a085-299cd76228dd","$feature_flag_id":7,"$feature_flag_version":3,"$feature_flag_reason":"Matched condition set 2","$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"user-id","event":"$feature_flag_called","$groups":[],"library":"posthog-php","library_version":"' . PostHog::VERSION . '","library_consumer":"LibCurl","groups":[],"timestamp":"2022-05-01T00:00:00+00:00","type":"capture"}],"api_key":"random_key"}',
+                    "payload" => '{"batch":[{"properties":{"$feature_flag":"multivariate-test","$feature_flag_response":"variant-value","$feature_flag_request_id":"98487c8a-287a-4451-a085-299cd76228dd","$feature_flag_id":7,"$feature_flag_version":3,"$feature_flag_reason":"Matched condition set 2","$lib":"posthog-php","$lib_version":"' . PostHog::VERSION . '","$lib_consumer":"LibCurl","$is_server":true,"$groups":[]},"distinct_id":"user-id","event":"$feature_flag_called","$groups":[],"groups":[],"timestamp":"2022-05-01T00:00:00+00:00"}],"api_key":"random_key"}',
                     "extraHeaders" => array(0 => 'User-Agent: posthog-php/' . PostHog::VERSION),
                     "requestOptions" => array('shouldVerify' => true),
                 ),