README

A PHP library that provides a fluent interface for making HTTP requests.

Installation

You can install the package via composer:

composer require solidworx/simple-http

This package is an implementation of PSR-18 (HTTP Client) and requires a PSR-18 compatible HTTP client. If you don't have one installed already, you can use Guzzle:

composer require guzzlehttp/guzzle php-http/guzzle7-adapter

Basic Usage

Creating a Client

use SolidWorx\SimpleHttp\HttpClient;

// Create a new client
$client = HttpClient::create();

// Create a client with a base URL
$client = HttpClient::createForBaseUrl('https://api.example.com');

Making a Simple GET Request

use SolidWorx\SimpleHttp\HttpClient;

$response = HttpClient::create()
    ->url('https://api.example.com/users')
    ->get()
    ->request();

// Get the response content as a string
$content = $response->getContent();

// Get the response status code
$statusCode = $response->getStatusCode();

// Get the response headers
$headers = $response->getHeaders();

Making a POST Request with JSON Data

use SolidWorx\SimpleHttp\HttpClient;

$response = HttpClient::create()
    ->url('https://api.example.com/users')
    ->post()
    ->json([
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ])
    ->request();

// Parse the JSON response into an array
$data = $response->toArray();

HTTP Methods

SimpleHttp supports all standard HTTP methods:

// GET request
$client->get()->request();

// POST request
$client->post()->request();

// PUT request
$client->put()->request();

// PATCH request
$client->patch()->request();

// DELETE request
$client->delete()->request();

// OPTIONS request
$client->options()->request();

// Custom method
$client->method('CUSTOM')->request();

Request Configuration

Headers

$client = HttpClient::create()
    ->url('https://api.example.com')
    ->header('Accept', 'application/json')
    ->header('X-API-Key', 'your-api-key');

Query Parameters

$client = HttpClient::create()
    ->url('https://api.example.com/search')
    ->query([
        'q' => 'search term',
        'page' => 1,
        'limit' => 10
    ]);

Request Body

Form Data

$client = HttpClient::create()
    ->url('https://api.example.com/form')
    ->post()
    ->formData([
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]);

JSON

$client = HttpClient::create()
    ->url('https://api.example.com/users')
    ->post()
    ->json([
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]);

Raw Body

$client = HttpClient::create()
    ->url('https://api.example.com/data')
    ->post()
    ->body('Raw request body content');

File Uploads

$client = HttpClient::create()
    ->url('https://api.example.com/upload')
    ->post()
    ->uploadFile('file', '/path/to/file.pdf');

Authentication

Basic Authentication

$client = HttpClient::create()
    ->url('https://api.example.com/protected')
    ->basicAuth('username', 'password');

Bearer Token Authentication

$client = HttpClient::create()
    ->url('https://api.example.com/protected')
    ->bearerToken('your-token');

SSL Configuration

Disable SSL Verification

$client = HttpClient::create()
    ->url('https://api.example.com')
    ->disableSslVerification();

HTTP Version

// Use HTTP/1.1 (default)
$client = HttpClient::create()
    ->url('https://api.example.com')
    ->httpVersion(HttpClient::HTTP_VERSION_1);

// Use HTTP/2
$client = HttpClient::create()
    ->url('https://api.example.com')
    ->http2();

Response Handling

Getting Response Data

$response = HttpClient::create()
    ->url('https://api.example.com/users')
    ->get()
    ->request();

// Get status code
$statusCode = $response->getStatusCode();

// Get headers
$headers = $response->getHeaders();
$contentType = $response->getHeaderLine('Content-Type');

// Get body as string
$content = $response->getContent();

// Parse JSON response
$data = $response->toArray();

Saving Response to a File

// Save to a file
$response = HttpClient::create()
    ->url('https://example.com/large-file.zip')
    ->get()
    ->saveToFile('/path/to/save/file.zip')
    ->request();

// Append to a file
$response = HttpClient::create()
    ->url('https://example.com/data.txt')
    ->get()
    ->appendToFile('/path/to/existing/file.txt')
    ->request();

// Save response to a file after receiving it
$response = HttpClient::create()
    ->url('https://example.com/image.jpg')
    ->get()
    ->request();

$response->saveToFile('/path/to/save/image.jpg');

Progress Tracking

$response = HttpClient::create()
    ->url('https://example.com/large-file.zip')
    ->progress(function ($progress) {
        // $progress->getDownloaded() - bytes downloaded
        // $progress->getTotal() - total bytes (if known)
        echo "Downloaded {$progress->getDownloaded()} of {$progress->getTotal()} bytes\n";
    })
    ->request();

Caching Responses

use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$cache = new FilesystemAdapter();

$response = HttpClient::create()
    ->url('https://api.example.com/data')
    ->cacheResponse($cache, 3600) // Cache for 1 hour
    ->request();

Error Handling

use SolidWorx\SimpleHttp\HttpClient;
use Http\Client\Exception\HttpException;

try {
    $response = HttpClient::create()
        ->url('https://api.example.com/users')
        ->get()
        ->request();
} catch (HttpException $e) {
    // Get the error response
    $errorResponse = $e->getResponse();

    // Get the status code
    $statusCode = $errorResponse->getStatusCode();

    // Get the error message
    $errorMessage = $e->getMessage();

    // Get the response body
    $errorBody = $errorResponse->getBody()->getContents();
}

Advanced Usage

Using with a Base URL

$client = HttpClient::createForBaseUrl('https://api.example.com');

// Now you can make requests to endpoints relative to the base URL
$response = $client->path('/users')->get()->request();
$response = $client->path('/posts')->get()->request();

Immutability

All methods in the SimpleHttp client return a new instance, making the client immutable:

$client = HttpClient::create()->url('https://api.example.com');

// These create new instances, they don't modify the original $client
$jsonClient = $client->header('Accept', 'application/json');
$authClient = $client->bearerToken('your-token');

// Original client remains unchanged
$response = $client->request();

This allows you to create reusable client configurations:

$baseClient = HttpClient::createForBaseUrl('https://api.example.com')
    ->bearerToken('your-token')
    ->header('Accept', 'application/json');

// Reuse the base client for different endpoints
$usersResponse = $baseClient->path('/users')->get()->request();
$postsResponse = $baseClient->path('/posts')->get()->request();

License

The MIT License (MIT). Please see License File for more information.