# `ClientHandler` Class API Reference

The `ClientHandler` class in FetchPHP provides a fluent API for building and sending HTTP requests. This class allows you to easily configure requests by chaining methods like `withHeaders()`, `withBody()`, `withToken()`, and more. It supports both synchronous and asynchronous requests, allowing flexible request handling based on your application's needs.

## Class Definition

```php
namespace Fetch\Http;

use Fetch\Interfaces\ClientHandler as ClientHandlerInterface;

class ClientHandler implements ClientHandlerInterface
```

The `ClientHandler` class is responsible for managing HTTP requests and providing methods to set various request options. It supports:

- Fluent API for constructing requests.
- Built-in retry and timeout mechanisms.
- Handling synchronous and asynchronous requests.
- Full support for configuring headers, body, query parameters, and more.

## Constructor

```php
public function __construct(
    ?ClientInterface $syncClient = null,
    array $options = [],
    ?int $timeout = null,
    ?int $retries = null,
    ?int $retryDelay = null,
    bool $isAsync = false
)
```

### Parameters

- **`$syncClient`** (ClientInterface|null): The synchronous HTTP client, typically an instance of Guzzle’s `Client`.
- **`$options`** (array): An array of options to configure the request, such as headers, method, etc.
- **`$timeout`** (int|null): Timeout in seconds for the request.
- **`$retries`** (int|null): Number of retries for the request in case of failure.
- **`$retryDelay`** (int|null): Delay in milliseconds between retries.
- **`$isAsync`** (bool): Indicates whether the request should be asynchronous.

## Available Methods

### **`handle()`**

```php
public static function handle(string $method, string $uri, array $options = []): mixed
```

Executes the HTTP request based on the provided method, URI, and options.

- **`$method`**: HTTP method (e.g., `GET`, `POST`).
- **`$uri`**: The URI for the request.
- **`$options`**: An array of request options.

**Returns**: A response object for synchronous requests or an `AsyncHelper` for asynchronous requests.

### **`baseUri()`**

```php
public function baseUri(string $baseUri): self
```

Sets the base URI for the request.

- **`$baseUri`**: The base URL for the request.

**Returns**: The `ClientHandler` instance for chaining.

### **`withHeaders()`**

```php
public function withHeaders(array $headers): self
```

Sets the headers for the request.

- **`$headers`**: An associative array of headers, where the key is the header name and the value is the header value.

**Returns**: The `ClientHandler` instance for chaining.

### **`withBody()`**

```php
public function withBody(mixed $body): self
```

Sets the request body.

- **`$body`**: The content of the body, which could be a string, array (for JSON), or other data.

**Returns**: The `ClientHandler` instance for chaining.

### **`withQueryParameters()`**

```php
public function withQueryParameters(array $queryParams): self
```

Adds query parameters to the request URL.

- **`$queryParams`**: An associative array of query parameters.

**Returns**: The `ClientHandler` instance for chaining.

### **`withToken()`**

```php
public function withToken(string $token): self
```

Adds a Bearer token for authentication.

- **`$token`**: The Bearer token string.

**Returns**: The `ClientHandler` instance for chaining.

### **`withAuth()`**

```php
public function withAuth(string $username, string $password): self
```

Adds Basic Authentication credentials.

- **`$username`**: Username for authentication.
- **`$password`**: Password for authentication.

**Returns**: The `ClientHandler` instance for chaining.

### **`timeout()`**

```php
public function timeout(int $seconds): self
```

Sets the timeout for the request.

- **`$seconds`**: Timeout in seconds.

**Returns**: The `ClientHandler` instance for chaining.

### **`retry()`**

```php
public function retry(int $retries, int $delay = 100): self
```

Configures retry logic for failed requests.

- **`$retries`**: Number of retry attempts.
- **`$delay`**: Delay in milliseconds between retries.

**Returns**: The `ClientHandler` instance for chaining.

### **`async()`**

```php
public function async(): self
```

Marks the request as asynchronous.

**Returns**: The `ClientHandler` instance for chaining.

### **`withProxy()`**

```php
public function withProxy(string|array $proxy): self
```

Sets a proxy server for the request.

- **`$proxy`**: A proxy URL or an array of proxy configurations.

**Returns**: The `ClientHandler` instance for chaining.

### **`withCookies()`**

```php
public function withCookies(bool|CookieJarInterface $cookies): self
```

Adds cookies to the request.

- **`$cookies`**: Either `true` to enable cookies, or an instance of `CookieJarInterface` to manage cookies.

**Returns**: The `ClientHandler` instance for chaining.

### **`withRedirects()`**

```php
public function withRedirects(bool|array $redirects = true): self
```

Configures whether the request should follow redirects.

- **`$redirects`**: Either `true` to follow redirects, or an array of redirect options.

**Returns**: The `ClientHandler` instance for chaining.

### **`withCert()`**

```php
public function withCert(string|array $cert): self
```

Specifies SSL certificates for the request.

- **`$cert`**: A path to the certificate or an array of certificate options.

**Returns**: The `ClientHandler` instance for chaining.

### **`withSslKey()`**

```php
public function withSslKey(string|array $sslKey): self
```

Specifies the SSL key for the request.

- **`$sslKey`**: A path to the SSL key or an array of key options.

**Returns**: The `ClientHandler` instance for chaining.

### **`withStream()`**

```php
public function withStream(bool $stream): self
```

Configures whether the request should be streamed.

- **`$stream`**: `true` to enable streaming.

**Returns**: The `ClientHandler` instance for chaining.

### **`get()`**

```php
public function get(string $uri): mixed
```

Sends a `GET` request.

- **`$uri`**: The URI for the request.

**Returns**: The response for synchronous requests, or `AsyncHelper` for async requests.

### **`post()`**

```php
public function post(string $uri, mixed $body = null): mixed
```

Sends a `POST` request.

- **`$uri`**: The URI for the request.
- **`$body`**: Optional request body.

**Returns**: The response for synchronous requests, or `AsyncHelper` for async requests.

### **`put()`**

```php
public function put(string $uri, mixed $body = null): mixed
```

Sends a `PUT` request.

- **`$uri`**: The URI for the request.
- **`$body`**: Optional request body.

**Returns**: The response for synchronous requests, or `AsyncHelper` for async requests.

### **`delete()`**

```php
public function delete(string $uri): mixed
```

Sends a `DELETE` request.

- **`$uri`**: The URI for the request.

**Returns**: The response for synchronous requests, or `AsyncHelper` for async requests.

### **`options()`**

```php
public function options(string $uri): mixed
```

Sends an `OPTIONS` request.

- **`$uri`**: The URI for the request.

**Returns**: The response for synchronous requests, or `AsyncHelper` for async requests.
