PHP Luminova: HTTP Request Clients

The HTTP request client is designed to simplify HTTP requests to external resources, such as APIs, web services, and websites. It simplifies the process of sending requests and efficiently handling responses, allowing you to read entire content or use the File Input Stream to read large contents in parts.

The Luminova HTTP clients provide an abstraction layer for handling HTTP requests. Follows PHP-FIG's standards for HTTP clients. These clients are designed with a consistent interface and support two implementations:

1. Luminova cURL Client
2. Luminova Guzzle Client

Both clients adhere to the Luminova\Interface\ClientInterface contract and the PSR-7 ClientInterface.

Luminova\Http\Network: Simplify HTTP request management using the Network class. It enables you to specify a client object (e.g., Curl or Guzzle) for handling HTTP requests seamlessly. Learn more.

Luminova cURL Client Implementations

• Namespace: \Luminova\Http\Client\Curl
• Description: A lightweight HTTP client based on PHP's native cURL extension. Ideal for environments with minimal dependencies.

Usage Example

use Luminova\Http\Client\Curl;

// Instantiate the cURL client
$curl = new Curl([
    'base_uri' => 'https://example.com/'
]);

// Send a GET request
$response = $curl->request('GET', 'foo', [
    'Content-Type' => 'text/html',
]);

echo $response->getBody()->getContents();

Features:

• Simple and Fast: Utilizes PHP's native cURL functions with support for (async requests, and more)
• Lightweight: No external dependencies.

Luminova Guzzle Client Implementations

• Namespace: \Luminova\Http\Client\Guzzle
• Description: An extended HTTP client powered by the Guzzle library. Provides advanced features and robust request handling.

Usage Example

use Luminova\Http\Client\Guzzle;

// Instantiate the Guzzle client
$guzzle = new Guzzle([
    'base_uri' => 'https://example.com/'
]);

// Send a GET request
$response = $guzzle->request('GET', 'foo', [
    'Content-Type' => 'text/html',
]);

echo $response->getBody()->getContents();

Features:

• Advanced Functionality: Leverages Guzzle's full feature set (async requests, middleware, and more).
• Extensible: Supports third-party plugins and middleware for enhanced capabilities.

Shared Interface

Both clients implement the following interfaces:

• Luminova\Interface\ClientInterface: A custom interface defining the HTTP client contract.
• Psr\Http\Client\ClientInterface: Ensures compliance with PSR-7 standards for HTTP clients.

Features of Luminova HTTP Clients

1. Consistent Interface
   Both Curl and Guzzle clients follow the same request syntax, making it easy to switch between implementations.

2. Base URI Support
   Allows setting a base URL for all subsequent requests, simplifying endpoint management.

3. Customizable Requests
   Supports:

   • HTTP headers
   • Query string parameters
   • Request body content
   • Timeout settings and more options

4. Compatibility

   • The Curl client requires only PHP's native cURL extension.
   • The Guzzle client requires the Guzzle library.

Comparison Table

Class Definition

• cURL Class Namespace: \Luminova\Http\Client\Curl
• Guzzle Class Namespace: \Luminova\Http\Client\Guzzle
• Class implements: \Luminova\Interface\ClientInterface, \Psr\Http\Client\ClientInterface

Methods

constructor

Initialize the HTTP request client constructor.

While making request, Use an absolute path to override the base_uri of the client, or a relative path to append to the base_uri of the client. The URL can contain the query string as well. Use an option-array to provide a URL template and additional variables to use in the URL template expansion.

public __construct(array<string,mixed> $config = []): mixed

Parameters:

getClient

Retrieve the original HTTP request client object.

public getClient(): \Psr\Http\Client\ClientInterface

Return Value:

\Psr\Http\Client\ClientInterface<\T> - Return instance of request client object such as Curl or Guzzle.

getConfig

Retrieve configuration option from client object.

public getConfig(?string $option = null): mixed

Parameters:

Return Value:

mixed - Return configuration option based on option name, or return all if option is null, otherwise null.

setOption

Set a custom cURL option and it's value.

public setOption(int $option, mixed $value): self

Parameters:

Return Value:

self - Return instance of request client class.

Note: The options will be ignored if used with Guzzle client.

sendRequest

Sends a request and returns response.

public sendRequest(\Psr\Http\Message\RequestInterface $request): \Psr\Http\Message\ResponseInterface

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface<\T> - Return instance of HTTP response object.

Throws:

• \Luminova\Exceptions\ClientException - If an error happens while processing the request.

sendAsync

Sends an HTTP request asynchronously to the specified URI.

Builds the request using the provided HTTP request object and optional configurations.

public sendAsync(
    \Psr\Http\Message\RequestInterface $request, 
    array<string,mixed> $options = []
): \Luminova\Interface\PromiseInterface

Parameters:

Return Value:

\Luminova\Interface\PromiseInterface - Return guzzle promise that resolves to the request response or cURL request response object.

Throws:

• \Luminova\Exceptions\RequestException - If the request format is invalid or fails.
• \Luminova\Exceptions\ConnectException - If the server cannot be reached.
• \Luminova\Exceptions\ClientException - For 4xx client-side HTTP errors.
• \Luminova\Exceptions\ServerException - For 5xx server-side HTTP errors.

requestAsync

Initiates an HTTP request asynchronously with a specified method and URI.

public requestAsync(
    string $method, 
    \Psr\Http\Message\UriInterface|string $uri = '', 
    array<string,mixed> $options = []
): \Luminova\Interface\PromiseInterface

Parameters:

Return Value:

\Luminova\Interface\PromiseInterface - Return guzzle promise that resolves to the request response or cURL request response object.

Throws:

• \Luminova\Exceptions\RequestException - If the request is improperly formatted or fails.
• \Luminova\Exceptions\ConnectException - If the server is unreachable.
• \Luminova\Exceptions\ClientException - For client-side HTTP errors (4xx responses).
• \Luminova\Exceptions\ServerException - For server-side HTTP errors (5xx responses).

send

Sends an HTTP request synchronously to the specified URI.

Uses the provided HTTP request object and optional settings to perform the request.

public send(
    \Psr\Http\Message\RequestInterface $request, 
    array<string,mixed> $options = []
): \Psr\Http\Message\ResponseInterface

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Return guzzle promise that resolves to the request response or cURL request response object.

Throws:

• \Luminova\Exceptions\RequestException - If the request format is invalid or fails.
• \Luminova\Exceptions\ConnectException - If a connection to the server cannot be established.
• \Luminova\Exceptions\ClientException - For 4xx client-side HTTP errors.
• \Luminova\Exceptions\ServerException - For 5xx server-side HTTP errors.

request

Performs a synchronous HTTP request to a specified URI.

Executes the request using the specified method and URI, with optional configurations to modify its behavior.

public request(string $method, string $uri = '', array<string,mixed> $options = []): \Psr\Http\Message\ResponseInterface

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Return the psr response interface object or cURL response object depending on client.

Throws:

• \Luminova\Exceptions\ConnectException - If a connection to the server cannot be established.
• \Luminova\Exceptions\RequestException - For request formatting, timeout, or protocol issues.
• \Luminova\Exceptions\ClientException - For client-side HTTP errors (4xx responses).
• \Luminova\Exceptions\ServerException - For server-side HTTP errors (5xx responses).