feature/support-request-options

README.md

@@ -78,6 +78,22 @@ $imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in t
 
 See the [`PromptBuilder` class](https://github.com/WordPress/php-ai-client/blob/trunk/src/Builders/PromptBuilder.php) and its public methods for all the ways you can configure the prompt.
 
+### Configuring request options
+
+You can configure HTTP transport options like timeout and maximum redirects using the `RequestOptions` DTO:
+
+```php
+use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
+
+// Set custom timeout for long-running requests
+$options = new RequestOptions(120, 10);
+
+// Or use defaults and modify
+$options = RequestOptions::defaults()->withTimeout(60);
+```
+
+For implementation ideas in different environments (WordPress, Guzzle, cURL), check the transporter-specific examples in the SDK source and tests.
+
 **More documentation is coming soon.**
 
 ## Further reading

src/Providers/Http/DTO/Request.php

@@ -23,7 +23,8 @@
  *     method: string,
  *     uri: string,
  *     headers: array<string, list<string>>,
- *     body?: string|null
+ *     body?: string|null,
+ *     options?: array<string, mixed>
  * }
  *
  * @extends AbstractDataTransferObject<RequestArrayShape>
@@ -34,6 +35,7 @@ class Request extends AbstractDataTransferObject
     public const KEY_URI = 'uri';
     public const KEY_HEADERS = 'headers';
     public const KEY_BODY = 'body';
+    public const KEY_OPTIONS = 'options';
 
     /**
      * @var HttpMethodEnum The HTTP method.
@@ -60,6 +62,11 @@ class Request extends AbstractDataTransferObject
      */
     protected ?string $body = null;
 
+    /**
+     * @var RequestOptions|null The request options.
+     */
+    protected ?RequestOptions $options = null;
+
     /**
      * Constructor.
      *
@@ -69,18 +76,25 @@ class Request extends AbstractDataTransferObject
      * @param string $uri The request URI.
      * @param array<string, string|list<string>> $headers The request headers.
      * @param string|array<string, mixed>|null $data The request data.
+     * @param RequestOptions|null $options The request options.
      *
      * @throws InvalidArgumentException If the URI is empty.
      */
-    public function __construct(HttpMethodEnum $method, string $uri, array $headers = [], $data = null)
-    {
+    public function __construct(
+        HttpMethodEnum $method,
+        string $uri,
+        array $headers = [],
+        $data = null,
+        ?RequestOptions $options = null
+    ) {
         if (empty($uri)) {
             throw new InvalidArgumentException('URI cannot be empty.');
         }
 
         $this->method = $method;
         $this->uri = $uri;
         $this->headers = new HeadersCollection($headers);
+        $this->options = $options;
 
         // Separate data and body based on type
         if (is_string($data)) {
@@ -281,6 +295,33 @@ public function getData(): ?array
         return $this->data;
     }
 
+    /**
+     * Gets the request options.
+     *
+     * @since n.e.x.t
+     *
+     * @return RequestOptions|null The request options or null if not set.
+     */
+    public function getOptions(): ?RequestOptions
+    {
+        return $this->options;
+    }
+
+    /**
+     * Returns a new instance with the specified options.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestOptions|null $options The request options.
+     * @return self A new instance with the options.
+     */
+    public function withOptions(?RequestOptions $options): self
+    {
+        $new = clone $this;
+        $new->options = $options;
+        return $new;
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -311,6 +352,10 @@ public static function getJsonSchema(): array
                     'type' => ['string'],
                     'description' => 'The request body.',
                 ],
+                self::KEY_OPTIONS => [
+                    'type' => 'object',
+                    'description' => 'The request options.',
+                ],
             ],
             'required' => [self::KEY_METHOD, self::KEY_URI, self::KEY_HEADERS],
         ];
@@ -337,6 +382,11 @@ public function toArray(): array
             $array[self::KEY_BODY] = $body;
         }
 
+        // Include options if present
+        if ($this->options !== null) {
+            $array[self::KEY_OPTIONS] = $this->options->toArray();
+        }
+
         return $array;
     }
 
@@ -349,11 +399,19 @@ public static function fromArray(array $array): self
     {
         static::validateFromArrayData($array, [self::KEY_METHOD, self::KEY_URI, self::KEY_HEADERS]);
 
+        $options = null;
+        if (isset($array[self::KEY_OPTIONS]) && is_array($array[self::KEY_OPTIONS])) {
+            /** @var array{timeout?: int|null, max_redirects?: int|null} $optionsArray */
+            $optionsArray = $array[self::KEY_OPTIONS];
+            $options = RequestOptions::fromArray($optionsArray);
+        }
+
         return new self(
             HttpMethodEnum::from($array[self::KEY_METHOD]),
             $array[self::KEY_URI],
             $array[self::KEY_HEADERS] ?? [],
-            $array[self::KEY_BODY] ?? null
+            $array[self::KEY_BODY] ?? null,
+            $options
         );
     }