Booze

A simple and elegant HTTP client library for PHP, built on top of Guzzle. Booze provides a clean, fluent interface for making HTTP requests with automatic response parsing, middleware support, and comprehensive error handling.

Features

• 🚀 Simple & Intuitive API - Clean, fluent interface for making HTTP requests
• 🔄 Automatic Response Parsing - Smart content-type detection and parsing (JSON, XML, plain text)
• 🛡️ Built-in Error Handling - Automatic exception throwing for HTTP error responses
• ⚙️ Middleware Support - Easy request/response manipulation with Guzzle middleware
• 📦 Multiple Request Types - Support for GET, POST, PUT, PATCH, DELETE with various content types
• 🎯 Type-Safe - Full type hints and return types for better IDE support

Requirements

• PHP 7.3 or higher
• ext-json
• ext-simplexml

Installation

Install via Composer:

composer require liopoos/booze

Quick Start

use Liopoos\Booze\Client;

class ApiClient extends Client
{
    public function __construct(array $guzzleOptions = [])
    {
        // Configure Guzzle options
        $guzzleOptions = array_merge([
            'base_uri' => 'https://api.example.com',
            'timeout' => 30,
        ], $guzzleOptions);

        parent::__construct($guzzleOptions);
    }
}

$client = new ApiClient();
$response = $client->get('/users');

Usage

Basic HTTP Methods

GET Request

// Simple GET request
$response = $client->get('https://httpbin.org/get');

// GET with query parameters
$response = $client->get('https://httpbin.org/get', [
    'page' => 1,
    'limit' => 10
]);

// GET with custom headers
$response = $client->get('https://httpbin.org/get', [], [
    'Authorization' => 'Bearer token123'
]);

POST Request

// POST with form data
$response = $client->post('https://httpbin.org/post', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// POST with JSON
$response = $client->postJson('https://httpbin.org/post', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// POST with multipart (file uploads)
$response = $client->postMultiPart('https://httpbin.org/post', [
    [
        'name' => 'file',
        'contents' => fopen('/path/to/file.jpg', 'r'),
        'filename' => 'file.jpg'
    ]
]);

PUT Request

// PUT with form data
$response = $client->put('https://httpbin.org/put', [
    'name' => 'Jane Doe'
]);

// PUT with JSON
$response = $client->putJson('https://httpbin.org/put', [
    'name' => 'Jane Doe'
]);

// PUT with multipart
$response = $client->putMultiPart('https://httpbin.org/put', [
    [
        'name' => 'data',
        'contents' => 'value'
    ]
]);

PATCH Request

// PATCH with JSON (default)
$response = $client->patch('https://httpbin.org/patch', [
    'name' => 'Updated Name'
]);

DELETE Request

// Simple DELETE
$response = $client->delete('https://httpbin.org/delete');

// DELETE with JSON body
$response = $client->deleteJson('https://httpbin.org/delete', [
    'reason' => 'No longer needed'
]);

Working with Headers

Set persistent headers for all requests:

$client->withHeaders([
    'Authorization' => 'Bearer your-token',
    'Accept' => 'application/json',
    'User-Agent' => 'MyApp/1.0'
]);

// All subsequent requests will include these headers
$response = $client->get('https://api.example.com/data');

Response Handling

Booze automatically parses responses based on the Content-Type header:

// JSON responses are automatically decoded to arrays
$response = $client->get('https://api.example.com/users');
// $response is an array

// XML responses are converted to arrays
$response = $client->get('https://api.example.com/data.xml');
// $response is an array

// Plain text responses are returned as strings
$response = $client->get('https://example.com/text');
// $response is a string

Error Handling

Booze provides specific exceptions for common HTTP errors:

use Liopoos\Booze\Exception\UnauthorizedHttpException;
use Liopoos\Booze\Exception\NotFoundHttpException;
use Liopoos\Booze\Exception\AccessDeniedHttpException;
use Liopoos\Booze\Exception\ApiException;

try {
    $response = $client->get('https://api.example.com/protected');
} catch (UnauthorizedHttpException $e) {
    // Handle 401 Unauthorized
    echo "Authentication failed: " . $e->getMessage();
} catch (AccessDeniedHttpException $e) {
    // Handle 403 Forbidden
    echo "Access denied: " . $e->getMessage();
} catch (NotFoundHttpException $e) {
    // Handle 404 Not Found
    echo "Resource not found: " . $e->getMessage();
} catch (ApiException $e) {
    // Handle all other HTTP errors (4xx, 5xx)
    echo "API error: " . $e->getMessage();
}

Advanced Usage

Custom Guzzle Configuration

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

class MyApiClient extends Client
{
    public function __construct()
    {
        $handler = HandlerStack::create();
        
        // Add custom middleware
        $handler->push(Middleware::log(
            $logger,
            new MessageFormatter('{method} {uri} HTTP/{version} {code}')
        ));
        
        parent::__construct([
            'handler' => $handler,
            'base_uri' => 'https://api.example.com',
            'timeout' => 30,
            'verify' => true,
            'http_errors' => false,
        ]);
    }
}

Accessing Raw Guzzle Client and Response

// Get the underlying Guzzle client
$guzzleClient = $client->getHttpClient();

// Get the last HTTP response object
$client->get('https://httpbin.org/get');
$httpResponse = $client->getHttpResponse();

// Access response details
$statusCode = $httpResponse->getStatusCode();
$headers = $httpResponse->getHeaders();
$body = $httpResponse->getBody();

API Reference

Client Methods

HTTP Methods

Method	Description	Parameters
get(string $url, array $query = [], array $headers = [])	Send GET request	URL, query parameters, headers
post(string $url, array $body = [], array $headers = [])	Send POST with form data	URL, form data, headers
postJson(string $url, array $body, array $headers = [])	Send POST with JSON	URL, JSON data, headers
postMultiPart(string $url, array $body, array $headers = [])	Send POST with multipart	URL, multipart data, headers
put(string $url, array $body = null, array $headers = [])	Send PUT with form data	URL, form data, headers
putJson(string $url, array $body = null, array $headers = [])	Send PUT with JSON	URL, JSON data, headers
putMultiPart(string $url, array $body = null, array $headers = [])	Send PUT with multipart	URL, multipart data, headers
patch(string $url, array $body = [], array $headers = [])	Send PATCH with JSON	URL, JSON data, headers
delete(string $url, array $headers = [])	Send DELETE request	URL, headers
deleteJson(string $url, array $body = [], array $headers = [])	Send DELETE with JSON	URL, JSON data, headers

Utility Methods

Method	Description	Returns
withHeaders(array $headers)	Set persistent headers for all requests	Client (chainable)
getHttpClient()	Get the underlying Guzzle client	\GuzzleHttp\Client
getHttpResponse()	Get the last HTTP response object	\GuzzleHttp\Psr7\Response

Exceptions

Exception	HTTP Status	Description
UnauthorizedHttpException	401	Authentication required or failed
AccessDeniedHttpException	403	Access forbidden
NotFoundHttpException	404	Resource not found
ApiException	Other 4xx/5xx	Generic API error

All exceptions extend \GuzzleHttp\Exception\TransferException.

Testing

Run the test suite:

# Run all tests
./vendor/bin/phpunit

# Run with detailed output
./vendor/bin/phpunit --testdox

# Run with code coverage
./vendor/bin/phpunit --coverage-html coverage

See tests/README.md for more information about the test suite.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This library is licensed under the MIT License. See the LICENSE file for details.

Credits

• Built on top of Guzzle HTTP Client
• Developed by hades

Support

If you encounter any issues or have questions, please open an issue on GitHub.