 |
VOOZH | about |
|
VOOZH | about |
This document explains the fluent interface design pattern as implemented throughout the Hypervel API Client codebase. A fluent interface enables method chaining by returning the object instance from methods, allowing readable, chainable configuration calls.
The fluent interface pattern is implemented across all core components: PendingRequest, ApiRequest, and ApiResponse. For information about how these components fit into the overall request lifecycle, see Core Architecture. For details on specific request configuration methods, see Request Configuration.
A fluent interface is an object-oriented API design pattern that uses method chaining to create more readable code. Each method returns an instance of the object (typically $this or static), allowing subsequent methods to be called on the returned value in a single expression.
Traditional approach:
Fluent interface approach:
Sources: General pattern analysis from src/PendingRequest.php67-167 src/ApiRequest.php24-212 src/ApiResponse.php14-66
The codebase uses the static return type for all fluent interface methods. This is a strategic choice that provides specific benefits over alternative return type declarations.
| Return Type | Description | Benefits | Drawbacks |
|---|---|---|---|
static | Late static binding | Works correctly with inheritance; subclasses return their own type | Slightly less specific than self |
self | Returns the class where method is defined | More explicit | Breaks inheritance; returns parent type in subclasses |
$this | Returns the exact instance | Most specific in PHPDoc | Not available as native return type in PHP |
The API client consistently uses static as the return type, which ensures that when subclasses extend ApiRequest, ApiResponse, or PendingRequest, the fluent interface continues to work correctly.
Example from ApiRequest:
Sources: src/ApiRequest.php48-51 src/ApiResponse.php36-42 src/PendingRequest.php67-72
The PendingRequest class implements fluent interfaces for configuring request execution behavior, middleware settings, and Guzzle options.
| Category | Methods | Return Type | Purpose |
|---|---|---|---|
| Middleware Toggle | enableMiddleware(), disableMiddleware() | static | Enable/disable middleware pipeline |
| Middleware Config | withRequestMiddleware(), withResponseMiddleware() | static | Set middleware arrays |
| Middleware Addition | withAddedRequestMiddleware(), withAddedResponseMiddleware() | static | Append to existing middleware |
| Options | withMiddlewareOptions(), withGuzzleOptions() | static | Configure execution options |
| Resource Type | withResource() | static | Set custom resource class |
| Delegation | __call() | static | Proxy to underlying HTTP client |
Sources: src/PendingRequest.php67-167 src/PendingRequest.php257-263
The ApiRequest class provides the most extensive fluent interface in the codebase, with over 20 chainable methods for building HTTP requests.
ApiRequest wraps a PSR-7 RequestInterface, which is immutable. Each fluent method creates a new PSR-7 request instance internally while maintaining the mutable fluent wrapper:
This hybrid approach allows for fluent chaining while maintaining PSR-7 compliance at the transport layer.
ApiRequest tracks whether data has been modified to defer expensive operations:
The data is only serialized and applied to the request body when toPsrRequest() is called src/ApiRequest.php217-224 optimizing performance when multiple data modifications occur.
Sources: src/ApiRequest.php24-29 src/ApiRequest.php48-63 src/ApiRequest.php78-105 src/ApiRequest.php126-137 src/ApiRequest.php182-212 src/ApiRequest.php217-240
The ApiResponse class provides a smaller but consistent fluent interface for modifying HTTP responses, primarily used by response middleware.
| Method | Parameters | Purpose | Return Type |
|---|---|---|---|
withStatus() | int $code, string $reasonPhrase | Modify response status code | static |
withProtocolVersion() | string $version | Set HTTP protocol version | static |
withHeader() | string $name, mixed $value | Set response header | static |
withAddedHeader() | string $name, mixed $value | Append to existing header | static |
withoutHeader() | string $name | Remove response header | static |
withBody() | StreamInterface $body | Replace response body | static |
Like ApiRequest, ApiResponse wraps an immutable PSR-7 ResponseInterface:
Sources: src/ApiResponse.php14-20 src/ApiResponse.php36-66
The codebase follows consistent naming patterns for fluent interface methods, making the API intuitive and predictable.
| Prefix | Meaning | Example | Behavior |
|---|---|---|---|
with* | Sets or replaces a value | withHeader(), withMethod() | Replaces existing value |
withAdded* | Appends to existing value | withAddedHeader(), withAddedRequestMiddleware() | Adds to existing values |
without* | Removes a value | withoutHeader(), withoutData() | Removes specified value |
as* | Transforms request format | asJson(), asForm() | Sets content type and format |
accept* | Sets Accept header | acceptJson(), accept() | Configures response expectations |
enable* / disable* | Toggles feature | enableMiddleware(), disableMiddleware() | Boolean feature toggle |
The naming conventions are consistent across all three fluent classes:
withHeader(), withAddedHeader(), withoutHeader()with* / without* patternwith* prefix for optionsSources: src/ApiRequest.php24-212 src/ApiResponse.php14-66 src/PendingRequest.php67-167
The fluent interface pattern integrates with PHP's magic method system to provide delegation and proxy functionality.
PendingRequest uses __call() to delegate unknown methods to the underlying HTTP client while maintaining fluent chaining:
This allows PendingRequest to expose all methods from ClientPendingRequest (from the hypervel/http-client package) without explicitly defining them.
When a method is called on PendingRequest:
PendingRequest, execute directlyConditionable trait, execute__call() - Delegate to underlying HTTP clientstatic - Maintain fluent chainThis creates a seamless API where client-specific configuration methods blend with HTTP client methods.
Sources: src/PendingRequest.php257-263 src/PendingRequest.php328-341
The fluent interface pattern in this codebase maintains type safety through PHP's generic type annotations, even though generics are not enforced at runtime.
Each fluent method in PendingRequest returns static (not self), preserving the generic type parameter:
The static return type ensures that when subclasses are created or when type parameters flow through the system, static analysis tools like PHPStan can track the specific resource type being returned.
| Aspect | Benefit | Example |
|---|---|---|
| IDE Autocomplete | Knows methods available after chaining | $client->withResource(User::class)->get() returns User |
| Static Analysis | Catches type errors before runtime | PHPStan validates resource class compatibility |
| Refactoring Safety | Find all usages of specific types | Renaming CustomResource finds all references |
| Documentation | Self-documenting API contracts | Generic annotations clarify return types |
Sources: src/PendingRequest.php18-29 src/PendingRequest.php150-167 src/PendingRequest.php175-233
All fluent methods in the codebase return static:
When one fluent method calls another, it directly returns the result to maintain the chain:
The PendingRequest class uses the Conditionable trait, which adds fluent conditional methods:
This pattern allows conditional configuration without breaking the fluent chain.
Sources: src/PendingRequest.php24 src/ApiRequest.php48-51
Summary: The fluent interface pattern is consistently implemented across PendingRequest, ApiRequest, and ApiResponse classes using static return types, consistent naming conventions (with*, without*, as*), and integration with magic methods for delegation. This design enables readable, chainable API configuration while maintaining type safety through generic type parameters and PSR-7 compliance through immutable request/response wrapping.
Refresh this wiki