PHP Luminova: Network - HTTP Request Client Helper

The Luminova Network class is a helper for sending HTTP requests with less boilerplate. Instead of creating a new client object every time, you can send requests directly using static methods that match common HTTP verbs (like get, post, put, etc.).

It also supports a config method to set default request options once at runtime — for example, in your application’s __construct, onCreate, or controller methods. This keeps your code consistent and avoids repeating setup.

Under the hood, the static methods use the Novio HTTP client. If you prefer Guzzle or another custom client, you can create a Network instance and pass in your own client object.

For full details, see the Request Client documentation.

Examples

Dynamic Methods

The network class supports a static dynamic method resolution for HTTP verbs such as GET, POST, PUT, etc.The config() method can be used to set default configuration (e.g., base_uri).

Examples:

// Send GET request
Network::get('https://example.com/');

// Send POST request
Network::post('https://example.com/', [
    'form_params' => [
        'foo' => 'bar'
    ]
]);

// Async requests 
Network::getAsync('https://example.com/')->then(function(ResponseInterface $response){
    // Handle
});
Network::postAsync('https://example.com/')->then(function(ResponseInterface $response){
    // Handle
});

Custom HTTP Client

You can initialize the Network class with either the Novio, Guzzle or other HTTP client. The client initialization options are immutable and cannot be overridden after initialization.

Initialization with Novio Client

use Luminova\Http\Client\Novio;

$client = Netwprk::client(new Novio(['base_uri' => 'https://example.com/']));

Initialization with Guzzle Client

To use the Network class with Guzzle client, ensure you have the required packages installed.Install it via Composer:

Command:

composer require guzzlehttp/guzzle

Guzzle Client Options:

When using Guzzle client all guzzle HTTP methods will be made available in the Network class, for more detailed about Guzzle client and available options, refer to the Guzzle documentation.

use Luminova\Http\Client\Guzzle;

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

Sending Requests

You can make HTTP requests using the get, post, and other methods provided by the Novio or Guzzle client class.

use Luminova\Https\Network;

// Set default class
Network::client($client);

// Full URL request
$response = Network::get('https://example.com/foo');

// Base URI request
$response = Network::get('foo');

// Post request
$response = Network::post('foo', [
    'form_params' => [
        'foo' => 'bar'
    ]
]);

Note:If you did not specify a base URI, you can pass the full URL directly in the request method.But can't use both features together.

Handling Responses

In this example, a GET request is sent using the default Novio client.

The response is then processed to retrieve the status code and content. Any exceptions are caught and handled appropriately.

if ($response->getStatusCode() === 200) {
    var_dump($response->getBody()->getContents());
}

Novio Specific Feature:

If you didn't specify stream option set to true, you can directly get the contents by simply calling getContents from the response object instead of $response->getBody()->getContents().

if ($response->getStatusCode() === 200) {
    var_dump($response->getContents());
}

Note: This is only available using the Novio client.

Response with Stream

Read response content in parts:

$response = Network::get('foo', [
    'stream' => true
]);

$body = $response->getBody();

while (!$body->eof()) {
    echo $body->read(1024);
}

On Header Received Callback

You can handle large responses with callbacks:

$response = Network::get('large-file', [
    'on_headers' => function (Luminova\Http\Message\Response $response, array $header) {
        if ($response->getHeaderLine('Content-Length') > 1024) {
            throw new \Exception('The file is too big!');
        }
    }
]);

Class Definition

• Class namespace: Luminova\Http\Network
• This class is a Final class

Constants

Constants in the network request class.

Methods

client

Set the HTTP client used by the Network class.

Overrides the default client for all outgoing requests.If not set, the default Luminova \Luminova\Http\Client\Novio client is used.

public static client(\Psr\Http\Client\ClientInterface $client): void

Parameters:

Luminova Clients:

• Luminova\Http\Client\Novio - Luminova HTTP client.
• Luminova\Http\Client\Guzzle - Guzzle HTTP client.

getClient

Retrieves the current HTTP client instance.

This method returns the Luminova Novio or Guzzle client object if it is being used; otherwise,it returns the client interface object.

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

Return Value:

\Psr\Http\Client\ClientInterface|null - Returns the instance of the HTTP client used for requests.

config

Define immutable global configurations for HTTP requests.

This method sets global options such as base_uri, headers, or timeouts. It must be called before making any network request (especially when using static methods), as the configuration becomes locked after the first usage.

public static config(array $config): void

Parameters:

Example:

Setting a base URL for all static requests:

Network::config([
    'base_uri' => 'https://example.com/'
]);

// Then, you can make relative requests:
Network::get('user/100/info');

Note:This method is best suited for static usage, where a default base URL or common settings (e.g., headers) are required across all requests.Once the client is created, the config cannot be changed.

send

Send a synchronous HTTP request using a request object.

Dispatches a fully configured request instance and returnsthe server response.

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

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Returns the request response object.

Throws:

• Luminova\Exceptions\Http\RequestException - Throws if an error occurs while making the request.
• Luminova\Exceptions\Http\ConnectException - Throws if a connection to the server cannot be established.
• Luminova\Exceptions\Http\ClientException - Throws if the client encounters an error (4xx HTTP status codes).
• Luminova\Exceptions\Http\ServerException - Throws if the server encounters an error (5xx HTTP status codes).

get

Execute a synchronous GET request.

Sends a GET request to the given URI and returns the server response.

public static get(
    \Psr\Http\Message\UriInterface|string $uri = '', 
    array<string,mixed> $options = []
): \Psr\Http\Message\ResponseInterface

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Returns the request response object.

Throws:

• Luminova\Exceptions\Http\RequestException - Throws if an error occurs while making the request.
• Luminova\Exceptions\Http\ConnectException - Throws if a connection to the server cannot be established.
• Luminova\Exceptions\Http\ClientException - Throws if the client encounters an error (4xx HTTP status codes).
• Luminova\Exceptions\Http\ServerException - Throws if the server encounters an error (5xx HTTP status codes).

fetch

Dispatch an HTTP request and return a promise.

By default, the request is sent asynchronously. To force synchronous execution, pass ['async' => false] in the options array.

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

Parameters:

Return Value:

\Luminova\Interface\PromiseInterface - Returns promise resolving to the HTTP response.

Example:

(new Network())
    ->fetch('https://example.com', 'GET', ['headers' => ['Accept' => 'application/json']])
    ->then(function (Psr\Http\Message\ResponseInterface $response) {
        echo $response->getBody()->getContents();
    })
    ->catch(function (Throwable $exception) {
        echo 'Error: ' . $exception->getMessage();
    });

post

Execute a synchronous POST request.

Sends a POST request to the given URI and returns the server response.

public static post(
    Psr\Http\Message\UriInterface|string $uri = '', 
    array<string,mixed> $options = []
): \Psr\Http\Message\ResponseInterface

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Returns the request response object.

Throws:

• Luminova\Exceptions\Http\RequestException - Throws if an error occurs while making the request.
• Luminova\Exceptions\Http\ConnectException - Throws if a connection to the server cannot be established.
• Luminova\Exceptions\Http\ClientException - Throws if the client encounters an error (4xx HTTP status codes).
• Luminova\Exceptions\Http\ServerException - Throws if the server encounters an error (5xx HTTP status codes).

request

Send a synchronous HTTP request.

Executes an HTTP request using the given method and URI and returns the server response.

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

Parameters:

Return Value:

\Psr\Http\Message\ResponseInterface - Returns the request response object.

Throws:

• Luminova\Exceptions\Http\RequestException - Throws if an error occurs while making the request.
• Luminova\Exceptions\Http\ConnectException - Throws if a connection to the server cannot be established.
• Luminova\Exceptions\Http\ClientException - Throws if the client encounters an error (4xx HTTP status codes).
• Luminova\Exceptions\Http\ServerException - Throws if the server encounters an error (5xx HTTP status codes).

sendAsync

Send an HTTP request asynchronously.

Dispatches the given request using the configured HTTP client and returns a promise that resolves to the response.

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

Parameters:

Return Value:

\Luminova\Interface\PromiseInterface - Promise resolving to the request response.

requestAsync

Send an HTTP request asynchronously using a URI.

Creates and dispatches an asynchronous request for the given HTTP methodand URI, returning a promise that resolves to the response.

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

Parameters:

Return Value:

\Luminova\Interface\PromiseInterface - Promise resolving to the request response.