Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk-php): document that timeout replaces read_timeout on Guzzle 8

Yudhi Armyndharisae626fe175d6
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index e48015ab7..537e173da 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -853,8 +853,8 @@ The constructor takes a single associative `$config` array:
| ------------------- | ------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl` | `string` | — (**required**) | API base URL, e.g. `http://localhost:2785`. A trailing `/` is stripped; any path prefix (e.g. `/v1` behind a proxy) is preserved. |
| `apiKey` | `string` | — (**required**) | Sent as the `X-API-Key` header on every request. Surrounding whitespace is trimmed; a control or non-ASCII character is refused. |
-| `timeout` | `float` | `30.0` | Per-request timeout in seconds. |
-| `httpClient` | `?\GuzzleHttp\ClientInterface` | `null` | Inject a Guzzle client (e.g. one built on a `MockHandler`) for testing or middleware. When `null`, a default Guzzle client is created with the configured timeout. |
+| `timeout` | `float` | `30.0` | Per-request timeout in seconds, applied to an injected `httpClient` too. On Guzzle 8 it is also sent as `read_timeout` (the stream handler's idle bound, `0` for none), replacing the injected client's own. The SDK has no separate idle setting. |
+| `httpClient` | `?\GuzzleHttp\ClientInterface` | `null` | Inject a Guzzle client (e.g. one built on a `MockHandler`) for testing or middleware. When `null`, a default Guzzle client is created with the configured timeout. On Guzzle 8 the SDK `timeout` replaces this client's `read_timeout` (see `timeout`). |
| `defaultHeaders` | `array<string,string>` | `[]` | Extra headers applied on every request, **under** the SDK's auth/JSON headers (which always win). A name must be an HTTP token; a value is text (a number is sent as its text) without a control or non-ASCII character, or an exception names the header. |
| `allowInsecureHttp` | `bool` | `false` | Skip the `error_log()` warning written for an `http://` `baseUrl` whose host is not localhost (e.g. a private Docker network or a TLS-terminating proxy). |
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 37ced8b00..1193814db 100644
--- a/sdk/php/README.md
+++ b/sdk/php/README.md
@@ -51,6 +51,8 @@ $client = new Client([
]);
```
+The SDK `timeout` (30 seconds by default) applies to every request, including those sent through an injected client, and overrides that client's own `timeout`. On Guzzle 8 it is also sent as `read_timeout`, the idle bound of Guzzle's stream handler (the one in use when ext-curl is missing, or when you inject a `StreamHandler`), so it replaces a `read_timeout` set on the injected client, and `0` removes that bound. The SDK has no separate idle-timeout setting: a stricter idle bound means a lower `timeout`, which also limits the whole call. cURL handlers ignore `read_timeout`, and Guzzle 7 leaves the injected client's value alone.
+
The optional `defaultHeaders` map accepts strings, scalar values, null, and non-empty lists of those values. Numbers, booleans, and null are converted to text. An empty list is rejected by header name before any request is sent because Guzzle 8 cannot represent a header with zero values. Use `''` for an empty header value.
## Messaging