chore: sync PHP client with Apify OpenAPI spec v2-2026-07-08T143931Z

- Bump API_SPEC_VERSION to v2-2026-07-08T143931Z and client version to 0.2.0
- Align User-Agent OS token with reference clients via Platform::osToken
  (WIN* -> win32, CYGWIN* -> cygwin, else lowercase PHP_OS)
- Add request-body compression for bodies >= 1024 bytes: brotli (Content-Encoding: br)
  when the PECL brotli extension is present, gzip (Content-Encoding: gzip) fallback
- Add zlib to CI setup-php extensions

Author: claude

.github/workflows/php-integration-tests.yml

@@ -35,7 +35,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.1'
-          extensions: mbstring, json, curl
+          extensions: mbstring, json, curl, zlib
           coverage: none
           tools: composer:v2
 

.github/workflows/php-publish.yml

@@ -45,7 +45,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.1'
-          extensions: mbstring, json, curl
+          extensions: mbstring, json, curl, zlib
           coverage: none
           tools: composer:v2
 

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0
+
+- Synced to Apify OpenAPI spec `v2-2026-07-08T143931Z`. No public interface changes.
+- Request bodies larger than 1024 bytes are now compressed before being sent, using brotli
+  (`Content-Encoding: br`) when the PECL `brotli` extension is available and gzip
+  (`Content-Encoding: gzip`) as a fallback. Matches the reference client's request compression.
+- The `User-Agent` OS token now reports the short lowercase platform identifier (e.g. `linux`,
+  `darwin`, `win32`), matching the reference JS client's `os.platform()` token, instead of the
+  upper-cased `PHP_OS_FAMILY` value.
+
 ## 0.1.1
 
 - Synced to Apify OpenAPI spec `v2-2026-07-07T132551Z`. No public interface changes.

src/ApifyClient.php

@@ -7,6 +7,7 @@
 use Apify\Client\Http\GuzzleHttpClient;
 use Apify\Client\Http\HttpClientInterface;
 use Apify\Client\Internal\HttpClientCore;
+use Apify\Client\Internal\Platform;
 use Apify\Client\Internal\RetryConfig;
 use Apify\Client\Model\ActorRun;
 use Apify\Client\Options\RequestQueueClientOptions;
@@ -347,7 +348,7 @@ private static function defaultIsAtHome(): bool
      */
     private static function buildUserAgent(?string $suffix, callable $isAtHomeFn): string
     {
-        $os = strtolower(PHP_OS_FAMILY);
+        $os = Platform::osToken(PHP_OS);
         $atHome = $isAtHomeFn() ? 'true' : 'false';
         $ua = sprintf('ApifyClient/%s (%s; PHP/%s); isAtHome/%s', Version::CLIENT_VERSION, $os, PHP_VERSION, $atHome);
         if ($suffix !== null && $suffix !== '') {

src/Internal/Compression.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Apify\Client\Internal;
+
+/**
+ * Optional request-body compression, matching the reference JS client's behaviour.
+ *
+ * Large request bodies are compressed before being sent, saving bandwidth on uploads (Actor inputs,
+ * key-value-store records, dataset item batches, ...). Brotli ({@code Content-Encoding: br}) is
+ * preferred when available and gzip ({@code Content-Encoding: gzip}) is used as a fallback.
+ *
+ * In PHP, brotli lives in the optional PECL {@code brotli} extension, which is frequently absent,
+ * while gzip ({@code gzencode}) ships with the standard {@code zlib} extension. We therefore prefer
+ * brotli only when the extension is loaded and fall back to gzip otherwise. Compression is
+ * best-effort: if neither codec is available (or a payload is too small), the body is sent
+ * unchanged rather than raising an error.
+ *
+ * @internal
+ */
+final class Compression
+{
+    /**
+     * Minimum body size (in bytes) worth compressing. Below this the CPU cost and the few bytes of
+     * codec framing outweigh the savings, so the body is left uncompressed. Matches the reference
+     * client's {@code MIN_COMPRESS_BYTES}.
+     */
+    public const MIN_COMPRESS_BYTES = 1024;
+
+    /**
+     * Brotli quality level. Level 6 mirrors the reference client and trades a little ratio for much
+     * faster compression than the brotli default (11).
+     */
+    private const BROTLI_QUALITY = 6;
+
+    /**
+     * Returns {@code [encoding, compressedBody]} when {@code $body} should be sent compressed, or
+     * {@code null} to send it unchanged. {@code $encoding} is the value for the
+     * {@code Content-Encoding} header ({@code 'br'} or {@code 'gzip'}).
+     *
+     * Only byte payloads at least {@see MIN_COMPRESS_BYTES} long are compressed. PHP strings are
+     * byte strings, so {@code strlen()} already measures the encoded size.
+     *
+     * @return array{0: string, 1: string}|null
+     */
+    public static function maybeCompress(string $body): ?array
+    {
+        if (strlen($body) < self::MIN_COMPRESS_BYTES) {
+            return null;
+        }
+
+        if (function_exists('brotli_compress')) {
+            // Called indirectly: brotli_compress only exists when the PECL brotli extension is
+            // loaded, so a direct call would be an unresolved reference for static analysis on the
+            // (common) PHP builds without the extension.
+            $brotliCompress = 'brotli_compress';
+            $compressed = $brotliCompress($body, self::BROTLI_QUALITY);
+            if (is_string($compressed)) {
+                return ['br', $compressed];
+            }
+        }
+
+        if (function_exists('gzencode')) {
+            $compressed = gzencode($body);
+            if ($compressed !== false) {
+                return ['gzip', $compressed];
+            }
+        }
+
+        return null;
+    }
+
+    private function __construct()
+    {
+    }
+}

src/Internal/HttpClientCore.php

@@ -70,6 +70,9 @@ public function call(
         bool $doNotRetryTimeouts = false,
         array $extraHeaders = []
     ): ResponseInterface {
+        // Compress the body once, up front, so every retry reuses the already-compressed payload.
+        [$body, $extraHeaders] = self::maybeCompressBody($body, $extraHeaders);
+
         $delayMillis = $this->retry->minDelayMillis;
         $maxAttempts = $this->retry->maxRetries + 1;
         $path = self::extractPath($url);
@@ -110,6 +113,46 @@ public function call(
         throw $lastError ?? new TransportException('request failed with no attempts');
     }
 
+    /**
+     * Compresses the request body when it is large enough to be worth it, returning the possibly
+     * replaced body together with the (possibly extended) header map. A caller that already set a
+     * {@code Content-Encoding} header is left untouched, so an explicitly-encoded body is never
+     * double-compressed.
+     *
+     * @param array<string,string> $extraHeaders
+     * @return array{0: string|null, 1: array<string,string>}
+     */
+    private static function maybeCompressBody(?string $body, array $extraHeaders): array
+    {
+        if ($body === null || self::hasHeader($extraHeaders, 'Content-Encoding')) {
+            return [$body, $extraHeaders];
+        }
+
+        $compressed = Compression::maybeCompress($body);
+        if ($compressed === null) {
+            return [$body, $extraHeaders];
+        }
+
+        [$encoding, $compressedBody] = $compressed;
+        $extraHeaders['Content-Encoding'] = $encoding;
+        return [$compressedBody, $extraHeaders];
+    }
+
+    /**
+     * Case-insensitive check for a header key, since HTTP header names are case-insensitive.
+     *
+     * @param array<string,string> $headers
+     */
+    private static function hasHeader(array $headers, string $name): bool
+    {
+        foreach (array_keys($headers) as $key) {
+            if (strcasecmp($key, $name) === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /** Opens a live streaming response (single attempt, no retry). Used by log streaming. */
     public function stream(string $url): ResponseInterface
     {

src/Internal/Platform.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Apify\Client\Internal;
+
+/**
+ * Derives the short, lowercase OS platform token used in the {@code User-Agent} header.
+ *
+ * The Apify clients agreed to report the operating system using the same short identifiers that
+ * Node's {@code os.platform()} yields (e.g. {@code linux}, {@code darwin}, {@code win32}), so a
+ * server-side parser sees one consistent value across every client. PHP's {@code PHP_OS} instead
+ * reports uname-style names ({@code Linux}, {@code Darwin}, {@code WINNT}, ...), so we translate
+ * the ones that differ and lowercase the rest.
+ *
+ * @internal
+ */
+final class Platform
+{
+    /**
+     * Translates a {@code PHP_OS}-style value into the short lowercase platform token used in the
+     * User-Agent header. Pass {@code PHP_OS} in production; the argument exists so the mapping can be
+     * unit-tested for every platform without depending on the host it runs on.
+     *
+     * Only two families need translating; everything else (Linux, Darwin, FreeBSD, OpenBSD, NetBSD,
+     * SunOS, ...) already matches Node's token once lowercased:
+     * - Windows: PHP reports {@code WINNT} (or {@code Windows}), Node reports {@code win32}.
+     * - Cygwin: PHP reports {@code CYGWIN_NT-10.0-...}, Node reports {@code cygwin}.
+     */
+    public static function osToken(string $phpOs): string
+    {
+        $upper = strtoupper($phpOs);
+        if (str_starts_with($upper, 'WIN')) {
+            return 'win32';
+        }
+        if (str_starts_with($upper, 'CYGWIN')) {
+            return 'cygwin';
+        }
+        return strtolower($phpOs);
+    }
+
+    private function __construct()
+    {
+    }
+}

src/Version.php

@@ -17,13 +17,13 @@ final class Version
      * The semantic version of this client library (see https://semver.org/).
      * Changes to the public interface other than additive ones are considered breaking changes.
      */
-    public const CLIENT_VERSION = '0.1.1';
+    public const CLIENT_VERSION = '0.2.0';
 
     /**
      * The version of the Apify OpenAPI specification this client was generated and verified
      * against. Corresponds to the {@code info.version} field of the Apify OpenAPI document.
      */
-    public const API_SPEC_VERSION = 'v2-2026-07-07T132551Z';
+    public const API_SPEC_VERSION = 'v2-2026-07-08T143931Z';
 
     private function __construct()
     {

tests/Unit/BatchAddRequestsTest.php

@@ -114,7 +114,7 @@ public function testRetriesOnlyUnprocessedFromSuccessfulResponse(): void
         self::assertSame([], $result->getUnprocessedRequests());
 
         // The retry must send only the still-unprocessed request (r1), not the whole batch again.
-        $retryBody = Json::decode((string) $transport->received[1]->getBody());
+        $retryBody = Json::decode(MockTransport::readBody($transport->received[1]));
         self::assertIsArray($retryBody);
         self::assertCount(1, $retryBody);
         self::assertSame('r1', $retryBody[0]['uniqueKey']);
@@ -150,7 +150,7 @@ public function testChunksByCountLimit(): void
         self::assertSame(2, $transport->callCount());
         self::assertCount(30, $result->getProcessedRequests());
         // First batch must respect the 25-request count limit.
-        $firstBody = Json::decode((string) $transport->received[0]->getBody());
+        $firstBody = Json::decode(MockTransport::readBody($transport->received[0]));
         self::assertIsArray($firstBody);
         self::assertCount(25, $firstBody);
     }
@@ -172,7 +172,7 @@ public function testChunksByPayloadByteSize(): void
 
         self::assertSame(2, $transport->callCount());
         self::assertCount(3, $result->getProcessedRequests());
-        $firstBody = Json::decode((string) $transport->received[0]->getBody());
+        $firstBody = Json::decode(MockTransport::readBody($transport->received[0]));
         self::assertIsArray($firstBody);
         self::assertCount(2, $firstBody); // byte limit, not the count limit, governed here
     }

tests/Unit/CompressionTest.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Apify\Client\Tests\Unit;
+
+use Apify\Client\Internal\Compression;
+use PHPUnit\Framework\TestCase;
+
+final class CompressionTest extends TestCase
+{
+    /** True when at least one compression codec is available in this PHP build. */
+    private static function hasCodec(): bool
+    {
+        return function_exists('brotli_compress') || function_exists('gzencode');
+    }
+
+    public function testSmallBodyIsNotCompressed(): void
+    {
+        $body = str_repeat('a', Compression::MIN_COMPRESS_BYTES - 1);
+        self::assertNull(Compression::maybeCompress($body));
+    }
+
+    public function testBodyAtThresholdIsCompressed(): void
+    {
+        if (!self::hasCodec()) {
+            self::markTestSkipped('no compression codec available in this PHP build');
+        }
+        // A body of exactly MIN_COMPRESS_BYTES is compressed (the below-threshold case is covered by
+        // testSmallBodyIsNotCompressed).
+        $result = Compression::maybeCompress(str_repeat('a', Compression::MIN_COMPRESS_BYTES));
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+        self::assertContains($encoding, ['br', 'gzip']);
+        self::assertNotSame('', $data);
+    }
+
+    public function testCompressedBodyRoundTrips(): void
+    {
+        if (!self::hasCodec()) {
+            self::markTestSkipped('no compression codec available in this PHP build');
+        }
+        $original = json_encode(['items' => array_fill(0, 500, ['field' => 'value-with-some-length'])]);
+        self::assertIsString($original);
+
+        $result = Compression::maybeCompress($original);
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+
+        // Highly repetitive JSON must shrink.
+        self::assertLessThan(strlen($original), strlen($data));
+
+        $decoded = self::decode($encoding, $data);
+        self::assertSame($original, $decoded);
+    }
+
+    public function testPrefersBrotliWhenAvailableElseGzip(): void
+    {
+        if (!self::hasCodec()) {
+            self::markTestSkipped('no compression codec available in this PHP build');
+        }
+        $result = Compression::maybeCompress(str_repeat('payload-', 500));
+        self::assertNotNull($result);
+        [$encoding] = $result;
+
+        $expected = function_exists('brotli_compress') ? 'br' : 'gzip';
+        self::assertSame($expected, $encoding);
+    }
+
+    private static function decode(string $encoding, string $data): string
+    {
+        if ($encoding === 'br') {
+            self::assertTrue(function_exists('brotli_uncompress'), 'brotli extension needed to decode');
+            // Called indirectly: the symbol only exists when the PECL brotli extension is loaded,
+            // so a direct call would be an unresolved reference for static analysis.
+            $brotliUncompress = 'brotli_uncompress';
+            $decoded = $brotliUncompress($data);
+        } else {
+            $decoded = gzdecode($data);
+        }
+        self::assertIsString($decoded);
+        return $decoded;
+    }
+}