PHP Luminova: HTTP Request Clients for Outgoing Network Requests

The HTTP client in Luminova simplifies making requests to external APIs, web services, and websites. It handles both simple and advanced use cases—whether you're reading full responses or streaming large payloads using the File Input Stream.

Luminova provides an abstraction layer for HTTP operations, following PHP-FIG standards for HTTP messages. Two interchangeable client implementations are supported:

1. Luminova cURL Client – A lightweight, native PHP cURL-based client.
2. Luminova Guzzle Client – A feature-rich client powered by the Guzzle library.

Both clients implement the Luminova\Interface\ClientInterface and comply with PSR-7 ClientInterface, ensuring consistent behavior across different implementations.

Tip: Use Luminova\Http\Network for simplified request handling. It lets you inject a client (like Curl or Guzzle) to manage HTTP calls transparently. Learn more.

cURL Client Class

• Namespace: Luminova\Http\Client\Curl

A lightweight HTTP client built on PHP's native cURL extension, ideal for environments with no external dependencies. This client supports both single and parallel requests using PHP’s CurlMultiHandle for efficient concurrent execution.

Single Request Example

use Luminova\Http\Client\Curl;

// Create a cURL client with base URI
$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();

Async Request with Promises

Send an asynchronous request that returns a promise, supporting both success and error handlers.

use Luminova\Http\Client\Curl;

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

$curl->requestAsync('GET', 'foo', [
    'Content-Type' => 'text/html',
])
->then(function(ResponseInterface $response) {
    echo $response->getBody()->getContents();
})
->catch(function(Exception $e) {
    echo $e->getMessage();
})
->error(function(Exception $e) {
    echo $e->getMessage();
});

Parallel Requests

Use PHP's CurlMultiHandle to queue and execute multiple requests concurrently.

use Luminova\Http\Client\Curl;

$multi = Curl::multi();

$multi
    ->add('GET', 'https://example.com')
    ->add('GET', 'https://example.org')
    ->add('GET', 'https://example.net');

Execute and Collect All Responses:

$multi->run();

$responses = $multi->getResponses();

var_export($responses);

// Example access:
// echo $responses[0]->getBody()->getContents();

Stream Each Response as It Completes:

foreach ($multi->iterator() as $result) {
    echo $result->getBody()->getContents();
}

Features

• Simple & Fast – Built on PHP’s native cURL for high performance.
• Asynchronous Support – Fire-and-forget requests with promise handling.
• Parallel Requests – Efficient concurrent execution with CurlMultiHandle.
• Zero Dependencies – Lightweight and self-contained.

Here’s an optimized and cleaner version of your Guzzle Client Class documentation, with corrections for typos and improved clarity:

Guzzle Client Class

• Namespace: \Luminova\Http\Client\Guzzle

An advanced HTTP client powered by the Guzzle library. This class offers robust request handling and additional capabilities over native cURL.Designed for consistency, it helps maintain a unified API when switching between the cURL and Guzzle clients in your application.

Request Example

use Luminova\Http\Client\Guzzle;

// Create a Guzzle client with a base URI
$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 – Full Guzzle feature support including async requests, retries, pools, and more.
• Extensible – Compatible with third-party middleware and plugins for logging, caching, etc.
• Consistent Interface – Shares a common API with the cURL client, making it easy to switch between them without rewriting your code.

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

Shared 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).