Request Configuration

Purpose

This page explains how to configure HTTP requests using the fluent interface provided by PendingRequest. It covers URL construction, Guzzle option configuration, and the delegation pattern that enables access to underlying HTTP client features.

For information about HTTP methods (GET, POST, etc.), see HTTP Methods. For headers and authentication configuration, see Headers and Authentication. For request body and data serialization, see Request Body and Serialization.

---

Overview

Request configuration in the API client is built on a fluent interface pattern that allows method chaining. The PendingRequest class provides configuration methods directly and also delegates to the underlying hypervel/http-client package for extended functionality.

Configuration Flow Diagram

The configuration process flows through two layers: PendingRequest for API-specific configuration and ClientPendingRequest for HTTP-level configuration.

Sources: src/PendingRequest.php22-263

---

URL Configuration

Basic URL Setting

URLs are specified as the first parameter to HTTP method calls. The URL can be absolute or relative to a base URL configured in the underlying HTTP client.

Sources: src/PendingRequest.php175-178

Dynamic URL Modification

The ApiRequest class supports dynamic URL modification through the withUrl() method, which accepts either a string or a callable that receives the current URL and returns a modified version.

URL Modification Flow

The callable pattern enables URL transformations in middleware or custom request builders:

The preserveHost parameter (default false) controls whether the Host header is updated when changing the URL.

Sources: src/ApiRequest.php34-43

---

Query Parameters

Query parameters are typically passed as the second argument to HTTP methods. For GET and HEAD requests, this parameter is specifically typed as array|JsonSerializable|string|null.

The underlying ClientPendingRequest from hypervel/http-client handles query parameter encoding and URL construction.

Sources: src/PendingRequest.php175-178 src/PendingRequest.php186-189

---

Guzzle Options

Overview

Guzzle options provide low-level control over HTTP request behavior. These options are passed directly to the Guzzle HTTP client that powers the underlying HTTP layer.

Guzzle Options Flow Diagram

Sources: src/PendingRequest.php97-102 src/PendingRequest.php328-341

Setting Guzzle Options

Use the withGuzzleOptions() method to configure Guzzle-specific behavior:

Common Guzzle Options

Option	Type	Description
timeout	float	Total request timeout in seconds
connect_timeout	float	Connection timeout in seconds
verify	bool|string	SSL certificate verification
proxy	string|array	Proxy server configuration
allow_redirects	bool|array	Redirect handling configuration
http_errors	bool	Whether to throw exceptions on HTTP errors
debug	bool|resource	Debug output configuration
headers	array	Default headers (use withHeaders() instead)
query	array	Query parameters (use method parameters instead)

For a complete list of Guzzle options, consult the Guzzle documentation.

When to Use Guzzle Options

Guzzle options should be used for:

• Network-level configuration: Timeouts, connection pooling, keep-alive
• Security settings: SSL verification, certificate paths
• Debugging: Request/response logging, debug output
• Advanced HTTP behavior: Custom stream contexts, curl options

For application-level concerns (headers, authentication, request transformation), use middleware or fluent methods instead.

Sources: src/PendingRequest.php97-102 src/PendingRequest.php336-338

---

Method Delegation

The __call() Magic Method

The PendingRequest class uses PHP's __call() magic method to delegate unknown method calls to the underlying ClientPendingRequest instance. This provides access to all HTTP client methods without explicitly wrapping each one.

Method Delegation Flow

Sources: src/PendingRequest.php257-263

Available Delegated Methods

Through delegation, PendingRequest provides access to all ClientPendingRequest methods, including:

Method Category	Example Methods
Request Body	withBody(), attach(), asMultipart()
Headers	withHeaders(), withToken(), withBasicAuth()
Options	withOptions(), timeout(), retry()
Cookies	withCookies(), withCookieJar()
Debugging	dump(), dd()

The delegation ensures that all methods return the PendingRequest instance for continued method chaining, even though the underlying operation is performed on ClientPendingRequest.

Delegation Implementation

The delegation mechanism is implemented as follows:

src/PendingRequest.php:257-263

The method:

1. Retrieves the ClientPendingRequest instance via getClient()
2. Invokes the requested method with provided parameters
3. Returns $this to maintain the fluent interface

This pattern allows the API client to stay focused on API-specific concerns while leveraging the full HTTP client functionality.

Sources: src/PendingRequest.php257-263 src/PendingRequest.php328-341

---

Configuration Method Reference

PendingRequest Configuration Methods

The following table lists all configuration methods available on PendingRequest:

Method	Parameters	Purpose
withGuzzleOptions()	array $options	Set Guzzle HTTP client options
withMiddlewareOptions()	array $options	Set options passed to middleware
withRequestMiddleware()	array $middleware	Set request middleware array
withAddedRequestMiddleware()	array $middleware	Add to existing request middleware
withResponseMiddleware()	array $middleware	Set response middleware array
withAddedResponseMiddleware()	array $middleware	Add to existing response middleware
withResource()	string $resource	Set custom resource class for response
enableMiddleware()	-	Enable middleware processing
disableMiddleware()	-	Disable middleware processing

All methods return static for method chaining.

Sources: src/PendingRequest.php67-167

ApiRequest Configuration Methods

The following table lists configuration methods on ApiRequest (accessible through delegation or middleware):

Method	Parameters	Purpose
withMethod()	string $method	Set HTTP method
withUrl()	callable|string $url, bool $preserveHost	Set or modify URL
withHeader()	string $key, string $value	Add single header
withHeaders()	array $headers	Add multiple headers
withAddedHeader()	string $key, string $value	Append to existing header
withAddedHeaders()	array $headers	Append to multiple headers
withoutHeader()	string $header	Remove single header
withoutHeaders()	array $headers	Remove multiple headers
withBody()	string $body	Set raw request body
withData()	array $data	Add to request data
withoutData()	array $data	Remove from request data

Sources: src/ApiRequest.php24-212

---

Complete Configuration Example

Complete Configuration Flow

The following example demonstrates a fully configured request:

This example shows configuration at three levels:

1. Guzzle options: Low-level HTTP behavior
2. Middleware options: API-specific processing configuration
3. Delegated methods: HTTP client fluent interface
4. Request execution: The final HTTP method call

Sources: src/PendingRequest.php97-102 src/PendingRequest.php87-92 src/PendingRequest.php257-263 src/PendingRequest.php175-178