Add support for Guzzle 8

* Add support for Guzzle 8

Allow guzzlehttp/guzzle ^8.0, guzzlehttp/promises ^3.0 and guzzlehttp/psr7 ^3.0
alongside the existing Guzzle 7 constraints (#429).

* Fix unsigned upload without `api_key`/`api_secret` (send no Basic auth when credentials are missing)
* Cast request header values to strings; skip unnamed (list-form) `headers` entries in HTTP request headers
* Handle any `Throwable` rejection from the HTTP client
* Test against both Guzzle 7 and Guzzle 8 in CI

Notes for Guzzle 8 users:
* Connect timeout defaults to 60 seconds when `connection_timeout` is not set
* Read timeouts are reported as `NetworkTimeoutException`, which is not a `ConnectException`
* Multipart parts no longer carry a per-part `Content-Length` header

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Reduce CI test matrix and skip duplicate PR runs

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: const-cloudinary

.github/workflows/test.yaml

@@ -2,7 +2,11 @@ name: Tests
 on: [push, pull_request]
 jobs:
   php:
-    name: PHP ${{ matrix.php-versions }}
+    name: PHP ${{ matrix.php-versions }}, Guzzle ${{ matrix.guzzle-versions }}
+    # Same-repo changes run on push; fork PRs run on pull_request.
+    if: >-
+      (github.event_name == 'push' && !github.event.pull_request.head.repo.fork) ||
+      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork)
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -13,6 +17,14 @@ jobs:
           - '8.2'
           - '8.3'
           - '8.4'
+        guzzle-versions:
+          - '7'
+        # Guzzle 8 on lowest and highest PHP only.
+        include:
+          - php-versions: '8.0'
+            guzzle-versions: '8'
+          - php-versions: '8.4'
+            guzzle-versions: '8'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -23,7 +35,9 @@ jobs:
           extensions: json
           coverage: xdebug
       - name: Install Composer dependencies
-        run: composer update -n
+        run: |
+          composer require -n --no-update guzzlehttp/guzzle:^${{ matrix.guzzle-versions }}
+          composer update -n
       - name: Run Tests
         run: |
           export CLOUDINARY_URL=$(bash tools/get_test_cloud.sh);

composer.json

@@ -26,9 +26,9 @@
   "require": {
     "php": ">=8.0.0",
     "cloudinary/transformation-builder-sdk":  "^2",
-    "guzzlehttp/guzzle": "^7.4.5",
-    "guzzlehttp/promises": "^1.5.3|^2.0",
-    "guzzlehttp/psr7": "^2.7",
+    "guzzlehttp/guzzle": "^7.4.5|^8.0",
+    "guzzlehttp/promises": "^1.5.3|^2.0|^3.0",
+    "guzzlehttp/psr7": "^2.7|^3.0",
     "ext-json": "*",
     "monolog/monolog": "^2|^3",
     "psr/log" : "^2|^3"

src/Api/ApiClient.php

@@ -418,10 +418,12 @@ protected function buildHttpClientConfig(): array
             $authConfig = [
                 'headers' => ['Authorization' => 'Bearer ' . $this->cloud->oauthToken],
             ];
-        } else {
+        } elseif (! empty($this->cloud->apiKey) && ! empty($this->cloud->apiSecret)) {
             $authConfig = [
                 'auth' => [$this->cloud->apiKey, $this->cloud->apiSecret],
             ];
+        } else {
+            $authConfig = [];
         }
 
         if (isset($authConfig['headers'])) {

src/Api/BaseApiClient.php

@@ -33,6 +33,7 @@
 use InvalidArgumentException;
 use JsonSerializable;
 use Psr\Http\Message\ResponseInterface;
+use Throwable;
 
 /**
  * Class BaseApiClient
@@ -297,9 +298,11 @@ protected static function finalizeEndPoint(array|string $endPoint): array|string
     protected function callAsync(string $method, array|string $endPoint, array $options): PromiseInterface
     {
         $endPoint           = self::finalizeEndPoint($endPoint);
-        $options['headers'] = ArrayUtils::mergeNonEmpty(
-            ArrayUtils::get($options, 'headers', []),
-            ArrayUtils::get($options, 'extra_headers', [])
+        $options['headers'] = self::normalizeHeaders(
+            ArrayUtils::mergeNonEmpty(
+                ArrayUtils::get($options, 'headers', []),
+                ArrayUtils::get($options, 'extra_headers', [])
+            )
         );
         $this->getLogger()->debug("Making async $method request", ['method' => $method, 'endPoint' => $endPoint]);
 
@@ -326,7 +329,7 @@ function (ResponseInterface $response) {
                         return Create::rejectionFor($e);
                     }
                 },
-                function (Exception $error) {
+                function (Throwable $error) {
                     $this->getLogger()->critical(
                         'Async request failed',
                         [
@@ -343,6 +346,28 @@ function (Exception $error) {
             );
     }
 
+    /**
+     * Keeps named headers only and casts their values to strings.
+     *
+     * @param array $headers The headers to normalize.
+     *
+     * @internal
+     */
+    private static function normalizeHeaders(array $headers): array
+    {
+        $normalized = [];
+
+        foreach ($headers as $name => $value) {
+            if (! is_string($name)) {
+                continue;
+            }
+
+            $normalized[$name] = is_array($value) ? array_map('strval', $value) : (string)$value;
+        }
+
+        return $normalized;
+    }
+
     /**
      * Provides the {@see ApiClient::$userAgent} string that is passed to the Cloudinary servers.
      *

src/Configuration/ApiConfig.php

@@ -65,7 +65,8 @@ class ApiConfig extends BaseConfigSection
 
     /**
      *  Describing the number of seconds to wait while trying to connect to a server.
-     *  Use 0 to wait indefinitely (the default behavior).
+     *  When not set, the HTTP client default applies (Guzzle 8: 60 seconds, Guzzle 7 with cURL: 300 seconds).
+     *  Use 0 to disable the limit on Guzzle 8; on Guzzle 7 with cURL, 0 selects the 300 seconds default.
      *
      * @var int|float|null
      */

tests/Unit/Admin/AssetsTest.php

@@ -363,9 +363,16 @@ public function testVisualSearchImageFile()
         $lastRequest = $mockAdminApi->getMockHandler()->getLastRequest();
 
         self::assertRequestUrl($lastRequest, '/resources/visual_search');
-        $body = $lastRequest->getBody()->getContents();
 
-        self::assertStringContainsString('image_file', $body);
-        self::assertStringContainsString('Content-Length: 5110', $body);
+        $file = array_values(
+            array_filter(
+                $mockAdminApi->getApiClient()->getRequestOptions()['multipart'],
+                static fn($part) => $part['name'] === 'image_file'
+            )
+        )[0];
+        $file['contents']->rewind();
+
+        self::assertSame(file_get_contents(IntegrationTestCase::TEST_IMAGE_PATH), $file['contents']->getContents());
+        self::assertSame('sample.png', $file['filename']);
     }
 }

tests/Unit/Upload/OAuthTest.php

@@ -112,5 +112,6 @@ public function testMissingCredentialsUnsignedUploadApi()
             self::API_TEST_PRESET,
             $uploadApi->getApiClient()->getRequestMultipartOptions()['upload_preset']
         );
+        self::assertArrayNotHasKey('Authorization', $uploadApi->getApiClient()->getLastRequestHeaders());
     }
 }

tests/Unit/Upload/UploadApiTest.php

@@ -205,6 +205,29 @@ public function headersDataProvider()
                 ],
                 [],
             ],
+            [
+                [
+                    'headers'       => ['X-Request-ID' => 12345],
+                    'extra_headers' => ['X-Debug' => [true, 1]],
+                ],
+                ['X-Request-ID' => ['12345'], 'X-Debug' => ['1', '1']],
+            ],
         ];
     }
+
+    /**
+     * Should send list-form `headers` as an upload parameter only, not as HTTP request headers.
+     */
+    public function testListFormHeadersAreNotSentAsHttpHeaders()
+    {
+        $mockUploadApi = new MockUploadApi();
+        $mockUploadApi->upload(self::TEST_BASE64_IMAGE, ['headers' => ['X-Robots-Tag: noindex']]);
+
+        self::assertArrayNotHasKey('0', $mockUploadApi->getApiClient()->getLastRequestHeaders());
+        self::assertArrayNotHasKey('X-Robots-Tag', $mockUploadApi->getApiClient()->getLastRequestHeaders());
+        self::assertSame(
+            'X-Robots-Tag: noindex',
+            $mockUploadApi->getApiClient()->getRequestMultipartOptions()['headers']
+        );
+    }
 }