HTTP Client

Introduction

Mantle provides a fluent and expressive wrapper around the WordPress HTTP APIopen in new window allowing you to quickly make HTTP requests with external services. The HTTP Client combined with support for testing and faking Remote Requests provides you a full solution for making and testing external HTTP requests end-to-end.

Future Plans

In the future, the HTTP Client will be abstracted to support the Guzzle HTTP Client and multipart requests. This also allows parallel requests to be made.

Making Requests

Making requests with the HTTP Client can be done using any HTTP verb such as get, head, post, put, delete and patch. Requests can be made using the Http facade class or by instantiating Mantle\Http_Client\Http_Client directly:

use Mantle\Facade\Http;

$response = Http::get( 'https://example.org/' );

Responses

The get method (and all other HTTP verb methods) return an instance of Mantle\Http_Client\Response, which provides a flexible wrapper on top of the raw WordPress HTTP API response.

$response->body()
$response->client_error(): bool
$response->collect( $key = null ): \Mantle\Support\Collection
$response->cookie( string $name ): ?\WP_HTTP_Cookie
$response->cookies(): array
$response->dd()
$response->dump()
$response->failed(): bool
$response->forbidden(): bool
$response->header( string $header )
$response->headers(): array
$response->is_json(): bool
$response->is_xml(): bool
$response->json( $key = null, $default = null )
$response->object()
$response->ok(): bool
$response->redirect(): bool
$response->response(): array
$response->server_error(): bool
$response->status(): int
$response->successful(): bool
$response->unauthorized(): bool
$response->xml( string $xpath = null, $default = null )

The Mantle\Http_Client\Response object also implements the ArrayAccess, allowing you to access JSON/XML response properties directly on the response.

return Http::get( 'https://httpbin.org/json' )['slideshow'];

Request Data

Many HTTP requests include some sort of a payload for POST, PUT, PATCH, and DELETE methods. These methods access an array of data as their second argument. By default these will be sent using JSON:

use Mantle\Facade\Http;

Http::post( 'http://example.org/endpoint', [
  'name' => 'Mantle',
] );

Sending a Body

Requests can also be made using a form body or a raw body:

use Mantle\Facade\Http;

Http::as_form()->post( 'http://example.org/endpoint', [
  'name' => 'Mantle',
] );

Http::with_body( 'raw-body' )->post( 'http://example.org/endpoint' );

GET Request Query Parameters

When making GET requests, you can either pass a URL with a query string directly or pass an array of key / value pairs as the second argument:

use Mantle\Facade\Http;

// The actual URL will be https://example.org/query?name=mantle
Http::get( 'https://example.org/query', [
  'name' => 'mantle',
] );

Headers

Headers can be added to a request using the with_header() and with_headers() methods:

Http::with_headers( [
  'X-Api-Key' => 'password',
] )->post( 'https://example.org' );

Http::with_header( 'X-Special-Header', 'value' )->post( 'https://example.org' );

The accept method can be used to specify the content type that your application is expecting in response:

Http::accept( 'text/plain' )->post( 'https://example.org' );
Http::accept_json()->post( 'https://example.org' );

Authentication

You can specify basic authentication and bearer token credentials with built-in helper methods:

Http::with_basic_auth( 'username', 'password' )->post( 'https://example.org' );

// Passed as Authorization: Bearer <value>
Http::with_token( '<value>' )->post( 'https://example.org' );

Timeout

The timeout method may be used to specify a maximum number of seconds to wait for a response. The default is 5 seconds:

Http::with_timeout( 10 )->post(...);

Retries

If you would like HTTP client to automatically retry the request if a client or server error occurs, you may use the retry method. The retry method accepts the maximum number of times the request should be attempted and the number of milliseconds that Mantle should wait in between attempts:

Http::retry( 3 )->post(...);

Base API Client

The HTTP Client can be used as a basis for a API Client for an external service. For example, if you are making requests to https://httpbin.org and want to include built-in authentication, you could create a reusable API client by returning Mantle\Http_Client\Http_Client:

use Mantle\Http_Client\Http_Client;

$client = Http_Client::create()
  ->base_url( 'https://httpbin.org' )
  ->with_token( '<token>' );

// Requests can now be made without specifying the base URL:
$response = $client->post( '/example-endpoint', [
  'name' => 'Mantle Http Client',
] );

Middleware

Requests can have middleware applied to them to allow the request and the response to be modified. One use case is to calculate a checksum header based on body of the request and pass that along with the request:

use Closure;
use Mantle\Http_Client\Http_Client;

$client = Http_Client::create()
  ->base_url( 'https://api.github.com' )
  ->middleware( function ( Http_Client $client, Closure $next ) {
    $client->with_header( 'Authorization', md5( $client->url() . $client->body() ) );

    // You can also run the callback and then modify the response.
    return $next( $client );
  } );

Use Outside of Mantle

The Http Client can be used separately outside of Mantle. Require the Http Client as a Composer Dependency:

composer require mantle-framework/http-client

You will then be able to use the Http Client to make requests like in the above examples:

use Mantle\Http_Client\Http_Client;

$response = Http_Client::create()->get( 'https://httpbin.org/json' );

// Access properties from the response.
$response->json( 'slideshow' );
$response['slideshow'];

# HTTP Client

# Introduction

# Making Requests

# Responses

# Request Data

# Sending a Body

# GET Request Query Parameters

# Headers

# Authentication

# Timeout

# Retries

# Base API Client

# Middleware

# Use Outside of Mantle