README

A collection of PHP HTTP client adapters to make swapping out HTTP client dependencies quick and easy.

Available adapters:

Requirements

PHP >= 8.0
Guzzle >= 6.5

Installation

To install the library, you will need to use Composer in your project.

composer require johnshopkins/http-exchange

Basic usage

Single request

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

$response = $http->get('http://httpbin.org/get');
$body = $response->getBody();
echo $body->url;

// prints: http://httpbin.org/get

Batch requests

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

$responses = $http->batch([
  ['get', 'http://httpbin.org/get'],
  ['post', 'http://httpbin.org/post']
]);

foreach ($responses as $response) {
  $body = $response->getBody();
  echo $body->url . "\n";
}

// prints:
// http://httpbin.org/get
// http://httpbin.org/post

Error handling

Single request

If a request fails, a HttpExchange\Exceptions\HTTP exception is thrown. See the exception methods documentation for more information.

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

try {
  $response = $http->get('http://httpbin.org/status/503');
  $body = $response->getBody();
} catch (\Exception $e) {
  echo $->getCode() . ': ' . $e->getMessage();
}

// prints:  503: Server error: `GET http://httpbin.org/status/503` resulted in a `503 SERVICE UNAVAILABLE` response

Batch requests

Instead of throwing a HttpExchange\Exceptions\HTTP when any one of the requests in a batch request fails, the exception is instead returned. This allows your application to gracefully handle failed requests, while processing successful ones.

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

$responses = $http->batch([
  ['get', 'http://httpbin.org/get'],
  ['get', 'http://httpbin.org/status/503']
]);

foreach ($responses as $response) {
  if ($response->getStatusCode() === 200) {
    $body = $response->getBody();
    echo $body->url . "\n";
  } else {
    echo $body->url . "This request failed :(\n";
  }
}

// prints:
// http://httpbin.org/get
// This request failed :(

Alternatively, you can check which kind of object was returned from each request (HttpExchange\Response or HttpExchange\Exceptions\HTTP) and proceed accordingly:

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

$responses = $http->batch([
  ['get', 'http://httpbin.org/get'],
  ['get', 'http://httpbin.org/status/503']
]);

foreach ($responses as $response) {
  if ($response instanceof HttpExchange\Response) {
    $body = $response->getBody();
    echo $body->url . "\n";
  } else {
    echo $body->url . "This request failed :(\n";
  }
}

// prints:
// http://httpbin.org/get
// This request failed :(

Documentation

Initialization

Guzzle 6

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle6($client);

Guzzle 7

$client = new GuzzleHttp\Client();
$http = new HttpExchange\Adapters\Guzzle7($client);

Adapter methods

`batch(array $requests)`

Send multiple requests concurrently.

Returns: array containing the result of each request. A HttpExchange\Response object indicates a successful request while a HttpExchange\Exceptions\HTTP exception object indicates a failed request.

Arguments:

$requests: An array of requests to make concurrently. Format:
```
$requests = [[$method, $url, $request_options], ...];
```
- $method: HTTP method
- $uri: Request URI
- $request_options: Request options to pass to HTTP client (Guzzle 6 or Guzzle 7)