HTTP Methods

The PendingRequest class provides dedicated methods for standard HTTP verbs (get(), post(), put(), patch(), delete(), head()) and a generic send() method for custom operations. All methods return an ApiResource instance and delegate internally to sendRequest() for unified processing. This page documents the available methods, their signatures, and the internal request dispatch mechanism.

For details on configuring request parameters and options, see page 5.2 (Request Configuration). For header and authentication configuration, see page 5.3 (Headers and Authentication). For request body serialization, see page 5.4 (Request Body and Serialization).

Available HTTP Methods

The PendingRequest class supports the following HTTP methods through dedicated methods:

Method	Description	Typical Use Case
get()	Retrieve data from the server	Fetching resources, search queries
head()	Get headers only (no response body)	Checking resource existence, metadata
post()	Send data to create resources	Creating new records, form submissions
patch()	Partial resource updates	Modifying specific fields
put()	Full resource replacement	Complete resource updates
delete()	Remove resources	Deleting records
send()	Generic method for any HTTP verb	Custom HTTP methods, advanced use cases

Method Dispatch Architecture

All HTTP method helpers in PendingRequest follow a unified dispatch pattern where they delegate to the internal sendRequest() method. This method orchestrates the complete request lifecycle, including middleware execution and resource transformation.

HTTP Method Dispatch Flow

Sources: src/PendingRequest.php175-243 src/PendingRequest.php265-291

Method Signatures and Parameters

GET and HEAD Methods

The get() and head() methods retrieve data from the server without sending a request body. Both accept optional query parameters:

Query Parameter Types:

Type	Example	Behavior
array	['page' => 1, 'limit' => 10]	Converted to query string
JsonSerializable	Custom object	Serialized then converted
string	"page=1&limit=10"	Used as-is
null	null	No query parameters

The head() method has the same signature as get() but returns only response headers without a body, useful for checking resource existence or metadata.

Sources: src/PendingRequest.php175-189

Data-Sending Methods (POST, PUT, PATCH, DELETE)

These methods send data in the request body and are used for creating, updating, or deleting resources:

Method Semantics and Data Types:

Method	Data Type	Typical Use Case	HTTP Semantics
post()	array|JsonSerializable	Create new resources	Non-idempotent creation
put()	array	Replace entire resource	Idempotent full replacement
patch()	array	Update specific fields	Partial modification
delete()	array (optional)	Remove resources	Deletion with optional filters

The post() method accepts JsonSerializable objects in addition to arrays, providing flexibility for domain objects. The data parameter is passed to the underlying HTTP client and serialized according to the configured content type (see page 5.4 for serialization details).

Sources: src/PendingRequest.php197-233

Generic Send Method

The send() method provides flexibility for custom HTTP verbs or advanced request configurations:

Parameters:

• $method: HTTP verb (e.g., 'OPTIONS', 'TRACE', or custom verbs)
• $url: Target URL
• $options: Array of options passed to the underlying ClientPendingRequest

This method is useful when working with:

• Custom HTTP methods not covered by dedicated helpers
• Complex request configurations requiring multiple options
• Non-standard HTTP operations

The $options array is passed directly to the underlying ClientPendingRequest::send() method from hypervel/http-client.

Sources: src/PendingRequest.php241-244

Internal Request Processing: sendRequest()

All HTTP method helpers delegate to the protected sendRequest() method at src/PendingRequest.php265-291 which orchestrates the complete request/response lifecycle.

Request Processing Sequence

Key Implementation Details:

1. Client Creation (src/PendingRequest.php328-341): The getClient() method lazily creates a ClientPendingRequest instance from hypervel/http-client, applying Guzzle options if configured.

2. Request Capture (src/PendingRequest.php272-278): The beforeSending() hook wraps the PSR-7 request in an ApiRequest object, enabling middleware processing and context management.

3. Middleware Execution (src/PendingRequest.php274-288): If enableMiddleware is true, requests and responses are processed through middleware pipelines via handleMiddlewareRequest() and handleMiddlewareResponse().

4. Resource Transformation (src/PendingRequest.php290): The final ApiResponse and ApiRequest are passed to the configured resource class (default: ApiResource) for transformation.

5. Async Rejection (src/PendingRequest.php280-282): If the underlying HTTP client returns a PromiseInterface, an InvalidArgumentException is thrown since async operations are not supported.

Sources: src/PendingRequest.php265-291 src/PendingRequest.php328-341

Method Forwarding via __call()

The PendingRequest class implements PHP's __call() magic method at src/PendingRequest.php257-263 to forward undefined method calls to the underlying ClientPendingRequest instance. This provides access to all configuration methods from hypervel/http-client without explicit delegation.

Magic Method Delegation Flow

Implementation:

This pattern allows PendingRequest to maintain a clean API surface while exposing the full functionality of the underlying HTTP client. The method returns $this to enable fluent chaining.

Common Forwarded Methods:

Method	Purpose	Package
withOptions()	Set Guzzle HTTP options	hypervel/http-client
withMiddleware()	Add HTTP middleware	hypervel/http-client
asJson()	Set JSON content type	hypervel/http-client
asForm()	Set form content type	hypervel/http-client
withHeaders()	Add request headers	hypervel/http-client
timeout()	Set request timeout	hypervel/http-client
retry()	Configure retry logic	hypervel/http-client

See the hypervel/http-client documentation for a complete list of available methods.

Sources: src/PendingRequest.php257-263

Return Type and Error Handling

All HTTP methods return an ApiResource instance (or a subclass specified via withResource()). The methods can throw ConnectionException for network-related errors and InvalidArgumentException for configuration issues.

The system explicitly rejects asynchronous requests by throwing an exception when a PromiseInterface is returned from the HTTP client.

Sources: src/PendingRequest.php262-263