Fetch HTTP Package - Overview

Introduction

The Fetch HTTP package provides a modern, flexible HTTP client for PHP applications, bringing JavaScript's fetch API experience to PHP. It features a fluent interface, extensive configuration options, and robust error handling, making it ideal for consuming APIs and working with web services.

Key Components

The package is comprised of several main components:

Client

The Client class is a high-level wrapper that:

• Implements PSR-18 ClientInterface for standardized HTTP client behavior
• Implements PSR-3 LoggerAwareInterface for easy integration with logging systems
• Provides a simple fetch-style API similar to JavaScript's fetch API
• Handles error conversion to specific exception types

ClientHandler

The ClientHandler class is a more powerful, configurable implementation that:

• Offers a fluent, chainable API for request building
• Provides extensive configuration options for request customization
• Supports both synchronous and asynchronous requests
• Implements retry logic with exponential backoff
• Offers promise-based operations for complex async workflows

Response

The Response class extends PSR-7 ResponseInterface and provides:

• Rich methods for working with HTTP responses
• Status code helpers like isOk(), isNotFound(), etc.
• Content type inspection with hasJsonContent(), hasHtmlContent(), etc.
• Convenient data access methods like json(), text(), array(), object()
• Array access interface for working with JSON responses

Enums

Type-safe PHP 8.1 enums for HTTP concepts:

• Method: HTTP methods (GET, POST, PUT, etc.)
• ContentType: Content types with helpers like isJson(), isText()
• Status: HTTP status codes with helpers like isSuccess(), isClientError()

Feature Highlights

• JavaScript-like API: Familiar syntax for developers coming from JavaScript
• PSR Compatibility: Implements PSR-18 (HTTP Client), PSR-7 (HTTP Messages), and PSR-3 (Logger)
• Fluent Interface: Chain method calls for clean, readable code
• Type-Safe Enums: Modern PHP 8.1 enums for HTTP methods, content types, and status codes
• Flexible Authentication: Support for Bearer tokens, Basic auth, and more
• Logging: Comprehensive request/response logging with sanitization of sensitive data
• Retries: Configurable retry logic with exponential backoff and jitter
• Asynchronous Requests: Promise-based async operations with concurrency control
• Content Type Handling: Simplified handling of JSON, forms, multipart data, etc.
• Testing Utilities: Built-in mock response helpers for testing

Architecture

+------------------+
|      Client      |  <-- High-level API (PSR-18 compliant)
+------------------+
          |
          v
+------------------+
|   ClientHandler  |  <-- Core implementation with advanced features
+------------------+
          |
    +-----------+
    |  Traits   |  <-- Functionality separated into focused traits
    +-----------+
    |  ConfiguresRequests
    |  HandlesUris
    |  ManagesPromises
    |  ManagesRetries
    |  PerformsHttpRequests
    +-----------+
          |
          v
+------------------+
|  Response        |  <-- Enhanced response handling
+------------------+
          |
          v
+------------------+
|  Guzzle Client   |  <-- Underlying HTTP client implementation
+------------------+

Usage Patterns

Simple Usage

// Global helper functions for quick requests
$response = fetch('https://api.example.com/users');
$users = $response->json();

// HTTP method-specific helpers
$user = post('https://api.example.com/users', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
])->json();

Advanced Configuration

The ClientHandler class offers more control and customization options for advanced use cases:

use Fetch\Http\ClientHandler;

$handler = new ClientHandler();
$response = $handler
    ->withToken('your-api-token')
    ->withHeaders(['Accept' => 'application/json'])
    ->withQueryParameters(['page' => 1, 'limit' => 10])
    ->timeout(5)
    ->retry(3, 100)
    ->get('https://api.example.com/users');

Type-Safe Enums

use Fetch\Enum\Method;
use Fetch\Enum\ContentType;
use Fetch\Enum\Status;

// Use enums for HTTP methods
$client = fetch_client();
$response = $client->request(Method::POST, '/users', $userData);

// Check HTTP status with enums
if ($response->statusEnum() === Status::OK) {
    // Process successful response
}

// Content type handling
$response = $client->withBody($data, ContentType::JSON)->post('/users');

Asynchronous Requests

For handling multiple requests efficiently:

use function async;
use function await;
use function all;

// Execute an async function
await(async(function() {
    // Create multiple requests
    $results = await(all([
        'users' => async(fn() => fetch('https://api.example.com/users')),
        'posts' => async(fn() => fetch('https://api.example.com/posts')),
        'comments' => async(fn() => fetch('https://api.example.com/comments'))
    ]));

    // Process the results
    $users = $results['users']->json();
    $posts = $results['posts']->json();
    $comments = $results['comments']->json();

    echo "Fetched " . count($users) . " users, " .
         count($posts) . " posts, and " .
         count($comments) . " comments";
}));

Global Client Configuration

// Configure once at application bootstrap
fetch_client([
    'base_uri' => 'https://api.example.com',
    'headers' => [
        'User-Agent' => 'MyApp/1.0',
        'Accept' => 'application/json',
    ],
    'timeout' => 10,
]);

// Use the configured client throughout your application
function getUserData($userId) {
    return fetch_client()->get("/users/{$userId}")->json();
}

function createUser($userData) {
    return fetch_client()->post('/users', $userData)->json();
}

Enhanced Response Handling

$response = fetch('https://api.example.com/users/1');

// Status code helpers
if ($response->isOk()) {
    // Handle 200 OK
} else if ($response->isNotFound()) {
    // Handle 404 Not Found
} else if ($response->isUnauthorized()) {
    // Handle 401 Unauthorized
}

// Status category helpers
if ($response->successful()) {
    // Handle any 2xx status
} else if ($response->isClientError()) {
    // Handle any 4xx status
} else if ($response->isServerError()) {
    // Handle any 5xx status
}

// Content type helpers
if ($response->hasJsonContent()) {
    $data = $response->json();
} else if ($response->hasHtmlContent()) {
    $html = $response->text();
}

// Array access for JSON responses
$user = $response['user'];
$name = $response['user']['name'];

When to Use Each Class

Use Client when

• You need PSR-18 compatibility
• You prefer a simpler API similar to JavaScript's fetch
• You're working within a framework that expects a PSR-18 client
• You want built-in exception handling for network and HTTP errors

Use ClientHandler when

• You need advanced configuration options
• You want to use asynchronous requests and promises
• You need fine-grained control over retries and timeouts
• You're performing complex operations like concurrent requests

Use global helpers (fetch(), get(), post(), etc.) when

• You're making simple, one-off requests
• You don't need extensive configuration
• You want the most concise, readable code

Exception Handling

The package provides several exception types for different error scenarios:

• NetworkException: For connection and network-related errors
• RequestException: For HTTP request errors
• ClientException: For unexpected client errors
• TimeoutException: For request timeouts

Each exception provides context about the failed request to aid in debugging and error handling.