title: fetch() description: API reference for the fetch() helper function#

fetch()#

The fetch() function is the primary way to make HTTP requests. It's designed to mimic JavaScript's fetch() API while providing PHP-specific enhancements.

Signature#

function fetch(
    string|RequestInterface|null $resource = null,
    ?array $options = []
): ResponseInterface|ClientHandlerInterface|Client

Parameters#

$resource#

• Type: string|RequestInterface|null
• Default: null

This parameter can be:

• A URL string to fetch, e.g., 'https://api.example.com/users'
• A pre-configured Request object
• null to return the client for method chaining

$options#

• Type: array|null
• Default: []

An associative array of request options:

Return Value#

The return value depends on the $resource parameter:

• If $resource is null: Returns the client instance (ClientHandlerInterface or Client) for method chaining
• If $resource is a URL string: Returns a ResponseInterface object
• If $resource is a Request object: Returns a ResponseInterface object

Throws#

• ClientExceptionInterface - If a client exception occurs during the request

Examples#

Basic GET Request#

use function Fetch\Http\fetch;

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

// Check if the request was successful
if ($response->successful()) {
    // Parse the JSON response
    $users = $response->json();

    foreach ($users as $user) {
        echo $user['name'] . "\n";
    }
} else {
    echo "Error: " . $response->status() . " " . $response->statusText();
}

POST Request with JSON Data#

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

// Or use the 'body' option with array (auto-converted to JSON)
$response = fetch('https://api.example.com/users', [
    'method' => 'POST',
    'body' => ['name' => 'John Doe', 'email' => 'john@example.com']
]);

Setting Headers#

$response = fetch('https://api.example.com/users', [
    'headers' => [
        'Accept' => 'application/json',
        'X-API-Key' => 'your-api-key',
        'User-Agent' => 'MyApp/1.0'
    ]
]);

Using Query Parameters#

// Add query parameters
$response = fetch('https://api.example.com/users', [
    'query' => [
        'page' => 1,
        'per_page' => 20,
        'sort' => 'created_at',
        'order' => 'desc'
    ]
]);

Form Submission#

// Send form data
$response = fetch('https://api.example.com/login', [
    'method' => 'POST',
    'form' => [
        'username' => 'johndoe',
        'password' => 'secret',
        'remember' => true
    ]
]);

File Upload#

// Upload a file using multipart form data
$response = fetch('https://api.example.com/upload', [
    'method' => 'POST',
    'multipart' => [
        [
            'name' => 'file',
            'contents' => file_get_contents('/path/to/file.jpg'),
            'filename' => 'upload.jpg',
            'headers' => ['Content-Type' => 'image/jpeg']
        ],
        [
            'name' => 'description',
            'contents' => 'Profile picture'
        ]
    ]
]);

Authentication#

// Bearer token authentication
$response = fetch('https://api.example.com/profile', [
    'token' => 'your-oauth-token'
]);

// Basic authentication
$response = fetch('https://api.example.com/protected', [
    'auth' => ['username', 'password']
]);

Timeouts and Retries#

// Set timeout and retry options
$response = fetch('https://api.example.com/slow-resource', [
    'timeout' => 30,           // 30 second timeout
    'retries' => 3,            // Retry up to 3 times
    'retry_delay' => 100       // Start with 100ms delay (uses exponential backoff)
]);

Method Chaining#

// Return the client for method chaining
$users = fetch()
    ->withToken('your-oauth-token')
    ->withHeader('Accept', 'application/json')
    ->get('https://api.example.com/users')
    ->json();

Using a Request Object#

use Fetch\Http\Request;

// Create a custom request
$request = Request::post('https://api.example.com/users')
    ->withJsonBody(['name' => 'John Doe', 'email' => 'john@example.com'])
    ->withHeader('X-API-Key', 'your-api-key');

// Send the request
$response = fetch($request);

Internal Implementation#

The fetch() function works by:

1. Processing the provided options with process_request_options()
2. Handling base URI configuration if provided with handle_request_with_base_uri()
3. Using the global client instance from fetch_client() to execute the request
4. Returning appropriate responses based on the input parameters

Notes#

• The fetch() function is not a direct implementation of the Web Fetch API; it's inspired by it but adapted for PHP
• When passing an array as the request body, it's automatically encoded as JSON
• For more complex request scenarios, use method chaining with fetch() or the ClientHandler class
• The function automatically handles conversion between different data formats based on content type
• When used without arguments, fetch() returns the global client instance for method chaining

See Also#

• fetch_client() - Get or configure the global client instance
• HTTP Method Helpers - Specialized helper functions for different HTTP methods
• ClientHandler - More details on the underlying client implementation
• Response - API for working with response objects