README

Lightweight, elegant HTTP client built with modern PHP. Provides an expressive and extensible wrapper to perform REST API calls using clean, typed interfaces. Aligned with Osirisgate Core standards.

📦 Installation

composer require osirisgate/http-client

✅ Requirements

• PHP 8.2 or higher
• osirisgate/core

✨ Features

• Simple and expressive methods for HTTP verbs: GET, POST, PUT, PATCH, DELETE
• Structured exception system implementing ExceptionInterface
• Response abstraction through ResponseInterface
• Optional support for:
  • Query parameters (filters)
  • Custom headers
  • Low-level request options

🧑‍💻 How to use it ?

✅ Send a GET request

use Osirisgate\Component\HttpClient\Request\Http;

$response = Http::get('https://jsonplaceholder.typicode.com/posts');
$data = $response->toArray();

📌 With query parameters

$response = Http::get(
    'https://jsonplaceholder.typicode.com/comments',
    filters: ['postId' => 1]
);

$comments = $response->toArray();

✍️ Create a resource (POST)

$response = Http::post(
    'https://jsonplaceholder.typicode.com/posts',
    payload: [
        'title' => 'foo',
        'body' => 'bar',
        'userId' => 1
    ]
);

🔁 Update a resource (PUT / PATCH)

// PUT (Full update)
$response = Http::put('https://jsonplaceholder.typicode.com/posts/1', payload: [
    'id' => 1,
    'title' => 'new title',
    'body' => 'updated content',
    'userId' => 1
]);

// PATCH (Partial update)
$response = Http::patch('https://jsonplaceholder.typicode.com/posts/1', payload: [
    'title' => 'patched title'
]);

❌ Delete a resource

$response = Http::delete('https://jsonplaceholder.typicode.com/posts/1');

⚙️ Advanced Configuration

🧾 Custom headers

$response = Http::get(
    'https://api.example.com/data',
    headers: [
        'Authorization' => 'Bearer TOKEN',
        'X-Custom-Header' => 'value'
    ]
);

🛠 Request options

The options parameter allows for fine-grained control over the underlying HTTP request. Here's a detailed overview of the available options:

• timeout: int (default: 30) - Sets the timeout of the request in seconds.
• max_redirects: int (default: 20) - Specifies the maximum number of redirects to follow.
• http_version: string|null (default: null) - Sets the HTTP protocol version (e.g., '1.1', '2.0').
• base_uri: string|null (default: null) - Sets a base URI for resolving relative URLs.
• headers: array (default: []) - An associative array of HTTP headers.
• auth_basic: array|null (default: null) - Enables HTTP basic authentication with ['username', 'password'].
• auth_bearer: string|null (default: null) - Sets the Authorization header with a bearer token.
• auth_ntlm: array|null (default: null) - Enables NTLM authentication with ['username', 'password'].
• query: array (default: []) - Associative array of query parameters to append to the URI.
• body: resource|string|null (default: null) - The raw request body.
• json: mixed|null (default: null) - If provided, will be JSON-encoded and used as the request body with the correct Content-Type.
• user_data: mixed|null (default: null) - Arbitrary user-defined data associated with the request.
• bindto: string|null (default: null) - Binds to a specific network interface or local port.
• proxy: string|null (default: null) - URI of a proxy server to use.
• no_proxy: string|null (default: null) - Comma-separated list of hostnames to bypass the proxy.
• verify_peer: bool (default: true) - Whether to verify the peer's SSL certificate. Set to false with caution in production.
• verify_host: bool (default: true) - Whether to verify the hostname against the SSL certificate.
• cafile: string|null (default: null) - Path to a custom CA bundle file for SSL verification.
• capath: string|null (default: null) - Path to a directory containing CA certificates.
• local_cert: string|null (default: null) - Path to a client-side certificate file for client authentication.
• local_pk: string|null (default: null) - Path to the private key file associated with local_cert.
• passphrase: string|null (default: null) - Passphrase for the private key.
• ciphers: string|null (default: null) - List of SSL/TLS ciphers to use.
• peer_fingerprint: array|null (default: null) - Verify the peer's certificate by its fingerprint (e.g., ['sha256' => '...]).
• capture_peer_cert_chain: bool (default: false) - Capture the peer's certificate chain for inspection via getInfo().
• extra: array (default: []) - Array of extra options to pass directly to the underlying HTTP client.

$response = Http::get(
    'https://api.example.com/data',
    options: [
        'timeout' => 5,
        'verify_peer' => false
    ]
);

🚨 Error Handling

Any HTTP client or server error will throw a typed exception implementing ExceptionInterface.

use Osirisgate\Core\Exception\ExceptionInterface;
use Osirisgate\Component\HttpClient\Request\Http;

try {
    $response = Http::get('https://api.example.com/invalid');
} catch (ExceptionInterface $e) {
    echo $e->getMessage(); // Not Found
    echo $e->getCode();    // 404
    print_r($e->format());
}

📄 Response Interface

Each request returns a structured object implementing ResponseInterface.

Get specific field from response
  * ex: $value = $response->get('user.firstname') // return user firstname value or null if not found
  * ex: $value = $response->get('user.account.balance') // return user account balance value or null if not found

🧪 Run Tests

A full suite of unit tests is included and runs against a public API (jsonplaceholder.typicode.com).

vendor/bin/phpunit tests

🧰 Developer Tools

✅ Code style

composer run phpcs-fix

🧠 Static analysis

composer run phpstan

Or run both checks at once:

make check-code-quality

📜 License

This package is licensed under the MIT License.

👤 Author

Ulrich Geraud AHOGLA Software Engineer — Osirisgate

If you have any questions or suggestions, please contact me via developer@osirisgate.com