test: cover both brotli and gzip compression paths; verify uniform OS token

Split Compression size-gate + codec selection into a testable compressWith()
seam (no behavior change) so both the brotli path and the gzip fallback are
covered deterministically regardless of whether the PECL brotli extension is
loaded. Add a unit-brotli CI job so the real brotli round-trip runs in CI, and
guard the gzip tests to skip on zlib-less builds. Add an AIX->aix case
asserting the User-Agent OS token matches the reference JS os.platform() token.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019xbC2QoA4QKyvhC1d7gYap

Author: claude

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

@@ -25,6 +25,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Offline unit tests on a build WITH the PECL brotli extension, so the real brotli codec round-trip
+  # (testRealBrotliRoundTripsWhenExtensionPresent) actually runs instead of self-skipping. The main
+  # `test` job deliberately omits brotli, so between the two jobs both request-compression codecs
+  # (brotli and the gzip fallback) get genuine real-codec coverage in CI. This job needs no API token.
+  unit-brotli:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up PHP (with brotli)
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.1'
+          extensions: mbstring, json, curl, zlib, brotli
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Fail if brotli extension missing
+        run: |
+          if ! php -r "exit(extension_loaded('brotli') ? 0 : 1);"; then
+            echo "::error::brotli extension failed to load; the real brotli codec test would silently skip."
+            exit 1
+          fi
+
+      - name: Unit tests (brotli path)
+        run: vendor/bin/phpunit --testsuite unit
+
   test:
     runs-on: ubuntu-latest
     steps:

CHANGELOG.md

@@ -9,6 +9,9 @@
 - 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.
+- Both request-compression codecs are now covered by deterministic tests: the brotli path (its
+  preference over gzip and its output) and the gzip fallback are each exercised regardless of whether
+  the host PHP build has the PECL `brotli` extension loaded. No behavior change.
 
 ## 0.1.1
 

src/Internal/Compression.php

@@ -45,32 +45,80 @@ final class Compression
      * @return array{0: string, 1: string}|null
      */
     public static function maybeCompress(string $body): ?array
+    {
+        return self::compressWith($body, self::brotliEncoder(), self::gzipEncoder());
+    }
+
+    /**
+     * Size gate plus codec selection, split out from {@see maybeCompress} so both the brotli and the
+     * gzip path can be exercised by tests regardless of which extensions the host PHP build loaded.
+     *
+     * Brotli ({@code br}) is preferred over gzip when its encoder is available; each encoder returns
+     * the compressed bytes as a string, or a non-string on failure, in which case the next codec is
+     * tried. Returns {@code null} when the body is below {@see MIN_COMPRESS_BYTES} or no codec
+     * succeeds. A {@code null} encoder means that codec is unavailable and is skipped.
+     *
+     * @param (callable(string): mixed)|null $brotli brotli encoder, or {@code null} when the PECL brotli extension is absent
+     * @param (callable(string): mixed)|null $gzip   gzip encoder, or {@code null} when zlib is absent
+     * @return array{0: string, 1: string}|null
+     */
+    public static function compressWith(string $body, ?callable $brotli, ?callable $gzip): ?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 ($brotli !== null) {
+            $compressed = $brotli($body);
             if (is_string($compressed)) {
                 return ['br', $compressed];
             }
         }
 
-        if (function_exists('gzencode')) {
-            $compressed = gzencode($body);
-            if ($compressed !== false) {
+        if ($gzip !== null) {
+            $compressed = $gzip($body);
+            if (is_string($compressed)) {
                 return ['gzip', $compressed];
             }
         }
 
         return null;
     }
 
+    /**
+     * The brotli encoder for this build, or {@code null} when the PECL {@code brotli} extension is not
+     * loaded. Frequently absent, since brotli is not part of PHP's standard distribution.
+     *
+     * @return (callable(string): mixed)|null
+     */
+    private static function brotliEncoder(): ?callable
+    {
+        if (!function_exists('brotli_compress')) {
+            return null;
+        }
+
+        // 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';
+        return static fn (string $body) => $brotliCompress($body, self::BROTLI_QUALITY);
+    }
+
+    /**
+     * The gzip encoder for this build, or {@code null} when {@code gzencode} (zlib) is unavailable.
+     * Ships with PHP's standard {@code zlib} extension, so it is the near-universal fallback.
+     *
+     * @return (callable(string): mixed)|null
+     */
+    private static function gzipEncoder(): ?callable
+    {
+        if (!function_exists('gzencode')) {
+            return null;
+        }
+
+        return static fn (string $body) => gzencode($body);
+    }
+
     private function __construct()
     {
     }

tests/Unit/CompressionTest.php

@@ -67,6 +67,90 @@ public function testPrefersBrotliWhenAvailableElseGzip(): void
         self::assertSame($expected, $encoding);
     }
 
+    public function testGzipPathWhenBrotliUnavailable(): void
+    {
+        if (!function_exists('gzencode')) {
+            self::markTestSkipped('zlib (gzencode) not available in this PHP build');
+        }
+        // Deterministically exercise the gzip fallback (brotli encoder absent) without depending on
+        // the host lacking the PECL brotli extension.
+        $original = str_repeat('payload-', 500);
+        $result = Compression::compressWith($original, null, static fn (string $b) => gzencode($b));
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+        self::assertSame('gzip', $encoding);
+        self::assertLessThan(strlen($original), strlen($data));
+        self::assertSame($original, gzdecode($data));
+    }
+
+    public function testBrotliPathIsPreferredWhenAvailable(): void
+    {
+        // Deterministically exercise the brotli path (and its preference over gzip) without depending
+        // on the host having the PECL brotli extension: inject a stand-in brotli encoder and assert it
+        // is chosen and its output used, while a real gzip encoder is also available.
+        $original = str_repeat('payload-', 500);
+        $marker = 'BR:' . $original;
+        $result = Compression::compressWith(
+            $original,
+            static fn (string $b) => 'BR:' . $b,
+            static fn (string $b) => gzencode($b),
+        );
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+        self::assertSame('br', $encoding);
+        self::assertSame($marker, $data);
+    }
+
+    public function testRealBrotliRoundTripsWhenExtensionPresent(): void
+    {
+        if (!function_exists('brotli_compress')) {
+            self::markTestSkipped('PECL brotli extension not loaded');
+        }
+        // When the real extension is present, verify the actual brotli codec produces decodable bytes.
+        $original = str_repeat('payload-', 500);
+        $result = Compression::maybeCompress($original);
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+        self::assertSame('br', $encoding);
+        self::assertLessThan(strlen($original), strlen($data));
+        self::assertSame($original, self::decode('br', $data));
+    }
+
+    public function testFallsBackToGzipWhenBrotliEncoderFails(): void
+    {
+        if (!function_exists('gzencode')) {
+            self::markTestSkipped('zlib (gzencode) not available in this PHP build');
+        }
+        // A brotli encoder that fails (returns a non-string) must not abort compression: gzip is used.
+        $original = str_repeat('payload-', 500);
+        $result = Compression::compressWith(
+            $original,
+            static fn (string $b) => false,
+            static fn (string $b) => gzencode($b),
+        );
+        self::assertNotNull($result);
+        [$encoding, $data] = $result;
+        self::assertSame('gzip', $encoding);
+        self::assertSame($original, gzdecode($data));
+    }
+
+    public function testReturnsNullWhenNoCodecAvailable(): void
+    {
+        $original = str_repeat('payload-', 500);
+        self::assertNull(Compression::compressWith($original, null, null));
+    }
+
+    public function testSmallBodyIsNotCompressedEvenWithCodecs(): void
+    {
+        // The size gate applies before codec selection, so a below-threshold body is never compressed.
+        $small = str_repeat('a', Compression::MIN_COMPRESS_BYTES - 1);
+        self::assertNull(Compression::compressWith(
+            $small,
+            static fn (string $b) => 'BR:' . $b,
+            static fn (string $b) => gzencode($b),
+        ));
+    }
+
     private static function decode(string $encoding, string $data): string
     {
         if ($encoding === 'br') {

tests/Unit/PlatformTest.php

@@ -27,6 +27,7 @@ public static function osCases(): array
             'openbsd' => ['OpenBSD', 'openbsd'],
             'netbsd' => ['NetBSD', 'netbsd'],
             'solaris/sunos' => ['SunOS', 'sunos'],
+            'aix' => ['AIX', 'aix'],
             'cygwin' => ['CYGWIN_NT-10.0-19045', 'cygwin'],
         ];
     }