title: API Reference for Fetch PHP description: API reference for the Fetch HTTP client package#

API Reference#

Welcome to the API reference for the Fetch HTTP client package. This section provides detailed documentation for all the components, functions, classes, and interfaces available in the package.

Core Components#

The Fetch package is built around several key components:

Functions#

• fetch() - The primary function for making HTTP requests
• fetch_client() - Function to create a configured HTTP client
• HTTP Method Helpers - Helper functions like get(), post(), etc.

Classes#

• Client - Main HTTP client class
• ClientHandler - Low-level HTTP client implementation
• Response - HTTP response representation

Enums#

• Method - HTTP request methods (GET, POST, PUT, etc.)
• ContentType - Content type (MIME type) constants
• Status - HTTP status codes

Architectural Overview#

The Fetch package is designed with a layered architecture:

1. User-facing API: The fetch(), fetch_client(), and HTTP method helpers (get(), post(), etc.) provide a simple, expressive API for common HTTP operations.

2. Client Layer: The Client class provides a higher-level, feature-rich API with method chaining and fluent interface.

3. Handler Layer: The ClientHandler class provides the core HTTP functionality, handling the low-level details of making HTTP requests.

4. HTTP Message Layer: The Response class represents HTTP responses and provides methods for working with them.

5. Utilities and Constants: Enums (Method, ContentType, Status) and other utilities provide standardized constants and helper functions.

Usage Patterns#

The API is designed to be used in several ways, depending on your needs:

One-line Requests#

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

// Quick POST request with JSON data
$response = fetch('https://api.example.com/users', [
    'method' => 'POST',
    'json' => [
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]
]);

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

Fluent Interface with Client#

// Create a client with a base URI
$client = fetch_client([
    'base_uri' => 'https://api.example.com'
]);

// Chain method calls for a more complex request
$response = $client
    ->getHandler()
    ->withHeader('X-API-Key', 'your-api-key')
    ->withQueryParameter('page', 1)
    ->timeout(5)
    ->get('/users');

Asynchronous Requests#

// Make an asynchronous request
$promise = fetch_client()
    ->getHandler()
    ->async()
    ->get('https://api.example.com/users');

// Add callbacks
$promise->then(
    function ($response) {
        // Handle successful response
        $users = $response->json();
        foreach ($users as $user) {
            echo $user['name'] . "\n";
        }
    },
    function ($exception) {
        // Handle error
        echo "Error: " . $exception->getMessage();
    }
);

Request Batching and Concurrency#

use function Fetch\async;
use function Fetch\await;
use function Fetch\all;
use function Fetch\map;

// Execute multiple requests in parallel
$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 multiple items with controlled concurrency
$userIds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
$results = await(map($userIds, function($id) {
    return async(function() use ($id) {
        return fetch("https://api.example.com/users/{$id}");
    });
}, 3)); // Process 3 at a time

Working with Enums#

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

// Make a request with enum values
$response = fetch_client()
    ->getHandler()
    ->withBody($data, ContentType::JSON)
    ->sendRequest(Method::POST, 'https://api.example.com/users');

// Check response status using enums
if ($response->getStatus() === Status::CREATED) {
    echo "User created successfully";
} elseif ($response->getStatus()->isClientError()) {
    echo "Client error: " . $response->getStatus()->phrase();
}

Extending the Package#

The package is designed to be extensible. You can:

• Create custom client handlers
• Extend the base client with additional functionality
• Add middleware for request/response processing
• Create specialized clients for specific APIs

See the Custom Clients guide for more information on extending the package.

Performance Considerations#

• Use the global client instance via fetch_client() for best performance, as it reuses connections
• Consider using asynchronous requests for I/O-bound operations
• Use the map() function with controlled concurrency for processing multiple items
• For large responses, consider streaming the response with the stream option

Compatibility Notes#

• Requires PHP 8.1 or higher
• Built on top of Guzzle HTTP, a widely-used PHP HTTP client
• Follows PSR-7 (HTTP Message Interface) and PSR-18 (HTTP Client) standards
• Supports both synchronous and asynchronous operations