Making Requests

Purpose and Scope

This section explains how to construct and execute HTTP requests using the hypervel/api-client package. It covers the complete request lifecycle, from initiating a request through the ApiClient to receiving an ApiResource response.

For detailed information about specific aspects of request handling:

• HTTP method options and usage patterns: see HTTP Methods
• URL construction, query parameters, and Guzzle options: see Request Configuration
• Header management and authentication: see Headers and Authentication
• Request body formatting and data serialization: see Request Body and Serialization

For information about processing responses after making requests, see Response Handling.

---

Request Lifecycle Overview

All requests in the hypervel/api-client package follow a consistent lifecycle pattern involving three primary classes: ApiClient, PendingRequest, and ApiRequest.

Request Flow Diagram

Sources: src/PendingRequest.php265-291 src/PendingRequest.php257-263

---

The PendingRequest Pattern

The ApiClient class serves as a factory and configuration container but does not directly execute requests. Instead, it delegates all HTTP method calls to PendingRequest instances through PHP's __call() magic method.

Delegation Mechanism

When you call an HTTP method on ApiClient:

The following delegation occurs:

1. ApiClient::__call() intercepts the method call
2. A new PendingRequest instance is created with the client's configuration
3. The method is forwarded to PendingRequest
4. PendingRequest orchestrates the request execution

This pattern provides several benefits:

Benefit	Description
Immutability	Each request gets a fresh PendingRequest instance
Configuration Inheritance	Settings from ApiClient are automatically passed to each request
Per-Request Customization	Individual requests can override client-level settings
Fluent Interface	Method chaining works naturally through the delegation pattern

Class Responsibility Map

Sources: src/PendingRequest.php53-62 src/PendingRequest.php257-263

---

Basic Request Execution

All HTTP requests are executed through PendingRequest methods. The package provides dedicated methods for common HTTP verbs plus a generic send() method for other cases.

HTTP Method Signatures

Method	Signature	Data Parameter Type
get()	get(string $url, array|JsonSerializable|string|null $query = null)	Query parameters
head()	head(string $url, array|string|null $query = null)	Query parameters
post()	post(string $url, array|JsonSerializable $data = [])	Request body
put()	put(string $url, array $data = [])	Request body
patch()	patch(string $url, array $data = [])	Request body
delete()	delete(string $url, array $data = [])	Request body
send()	send(string $method, string $url, array $options = [])	Generic options

All methods return an ApiResource instance (or a custom subclass specified via withResource()).

Sources: src/PendingRequest.php170-244

---

Request Building Process

Behind the scenes, PendingRequest coordinates a multi-step process to build and execute requests:

Internal Request Flow

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

Key Steps Explained

1. HTTP Client Creation - getClient() lazily instantiates a ClientPendingRequest from hypervel/http-client with Guzzle options applied
2. Before-Send Hook - beforeSending() callback wraps the PSR-7 request in ApiRequest for enhanced functionality
3. Request Middleware - If enabled, the request passes through the middleware pipeline for transformations
4. HTTP Execution - The underlying HTTP client sends the request to the external API
5. Response Wrapping - The raw response is wrapped in ApiResponse for enhanced functionality
6. Response Middleware - If enabled, the response passes through its middleware pipeline
7. Resource Creation - ApiResource::make() creates the final typed response object

---

Request Configuration Methods

PendingRequest provides fluent methods to configure various aspects of request execution. These methods return static to enable method chaining.

Configuration Categories

Sources: src/PendingRequest.php67-167

Method Categories

Category	Methods	Purpose
Middleware Control	enableMiddleware(), disableMiddleware(), withMiddlewareOptions()	Enable/disable middleware pipelines and pass configuration
Middleware Registration	withRequestMiddleware(), withAddedRequestMiddleware(), withResponseMiddleware(), withAddedResponseMiddleware()	Configure which middleware classes to execute
HTTP Options	withGuzzleOptions()	Pass low-level Guzzle configuration (timeouts, proxies, etc.)
Resource Type	withResource()	Specify a custom ApiResource subclass for type-safe responses
Conditional	when(), unless()	Conditionally apply configuration based on boolean conditions

The Conditionable trait (via use Conditionable at src/PendingRequest.php24) provides the when() and unless() methods for conditional configuration.

---

ApiRequest Builder Methods

While PendingRequest orchestrates request execution, ApiRequest provides the actual request building capabilities. These methods are typically used within middleware to modify requests, but they demonstrate the underlying request construction API.

Request Modification Categories

Sources: src/ApiRequest.php24-212

Fluent Modification Pattern

All ApiRequest methods follow an immutable pattern:

1. Methods return static for method chaining
2. The underlying PSR-7 request is wrapped and modified through immutable with*() methods
3. Changes are tracked via the $dataChanged flag for deferred serialization
4. toPsrRequest() finalizes all changes and returns the PSR-7 RequestInterface

Sources: src/ApiRequest.php19-20 src/ApiRequest.php217-240

---

Request Execution Architecture

The following diagram maps the complete request execution architecture to actual code entities:

Sources: src/PendingRequest.php257-263 src/PendingRequest.php265-291 src/PendingRequest.php328-341 src/ApiRequest.php217-224

---

Summary

Making requests with hypervel/api-client follows a well-defined pattern:

1. Initiation - Call an HTTP method on ApiClient (e.g., $client->get())
2. Delegation - ApiClient creates a PendingRequest and forwards the call
3. Configuration - Optionally chain configuration methods on PendingRequest
4. Building - ApiRequest constructs the HTTP request with headers, body, and metadata
5. Middleware - Optional request middleware transforms the outgoing request
6. Execution - The HTTP client sends the request to the external API
7. Response Middleware - Optional response middleware transforms the incoming response
8. Resource Creation - The response is wrapped in an ApiResource for type-safe access

The following child pages provide detailed coverage of each aspect:

• HTTP Methods - All available HTTP verbs and the generic send() method
• Request Configuration - URL building, query parameters, and Guzzle options
• Headers and Authentication - Managing headers and authentication tokens
• Request Body and Serialization - Data encoding and content-type handling

Sources: src/PendingRequest.php src/ApiRequest.php