Download the PHP package rexlabs/hyper-http without Composer

Deprecated

This library isn't in active development.

Please consider guzzlehttp/guzzle or another library instead.

Bug fixes only.

Hyper Http Client

Overview

Hyper is an HTTP Client that aims to provide a simple, but powerful interface for making HTTP calls and fetching and manipulating API data.

Why use Hyper

• Extremely simple interface Hyper::get('http://some/url').
• Also supports object style Hyper::make(...)->get('http://some/url').
• Provides a Response object which provides useful information like HTTP status code, body and headers.
• Every Response mixes in rexlabs\array-object which allows you to easily interrogate API responses.
• Throws a limited set of exceptions (with access to the request and/or response) when things go wrong.
• You have access to the original Request via $response->getRequest().
• Supports all of Guzzle client functionality including streams.
• Allows you to dump cURL requests for reproducing from the command-line.
• Easily log all requests

Usage

Installation

To install in your project:

Examples

The RESTful methods all return a Response object which makes interacting with responses simple.

Example: Using static methods

Example: Working with a JSON API

Since responses mixin ArrayObject you can easily fetch and manipulate values from the response:

Example: Set global headers and pass in a logger

Use make() to simplify instantiation and then setup the object for future requests:

• $hyper = Hyper::make(array $config = [], \GuzzleHttp\Client $guzzle, \Psr\Log\LoggerInterface $logger)

Example: Instantiation via constructor

To get complete control over instantiation, use the constructor and pass in a Guzzle instance:

Example: Dumping a cURL request

You can easily generate a cURL request for running from the command-line to reproduce your last request:

Output:

Http Methods

Hyper provides the following methods for interacting with remote endpoints:

get()

get(mixed $uri, array $query = [], array $headers = [], array $options = []): Response

Send an HTTP GET request, and return the Response:

• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $query is an optional array of query parameters which will be appended to the uri.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

post()

post(mixed $uri, mixed $body = null, array $headers = [], array $options = []): Response

Send an HTTP POST request, and return the Response:

• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $body is the payload. If you provide an array, it will be converted and transported as json.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

Alternative methods:

• $response = $hyper->postForm($uri, $formParams, $headers, $options);
• $response = $hyper->postMultipartForm($uri, $formParams, $headers, $options);

put()

put(mixed $uri, mixed $body = null, array $headers = [], array $options = []): Response

Send an HTTP PUT request, and return the Response:

• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $body is the payload. If you provide an array, it will be converted and transported as json.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

patch()

patch(mixed $uri, mixed $body = null, array $headers = [], array $options = []): Response

Send an HTTP PATCH request, and return the Response:

• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $body is the payload. If you provide an array, it will be converted and transported as json.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

delete()

delete(mixed $uri, mixed $body = null, array $headers = [], array $options = []): Response

Send an HTTP DELETE request, and return the Response:

• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $body is the optional payload. If you provide an array, it will be converted and transported as json.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

call()

call(string $method, mixed $uri, mixed $body, array $headers, array $options): Response

Send a generic HTTP request by specifying the method as the first argument.

• $method is the HTTP verb. Eg. GET or something not part of the standard.
• $uri is a string or a Uri. If the string is not absolute it will be appended to the base uri.
• $body is the optional payload. If you provide an array, it will be converted and transported as json.
• $headers is an optional array of headers (indexed by header name) that will be merged with any global headers.
• $options is an optional array of Guzzle client options.

Request Methods

Methods available from the Rexlabs\HyperHttp\Message\Request object:

getUri()

Return the UriInterface object which encapsulates the URI/URL for this request.

getMethod()

Return the HTTP method verb for this Request.

getHeaders()

Retur an array of headers for this Request

getCurl()

Return a cURL request (string) suitable for running from the command-line. Useful for debugging requests.

Response Methods

Methods available from the Rexlabs\HyperHttp\Message\Response object:

getRequest()

Return the Rexlabs\HyperHttp\Message\Request object associated with the Response

getCurlRequest()

Return a cURL request (string) suitable for running from the command-line. Useful for debugging requests.

getStatusCode()

Return the HTTP status code for this Response. EG. 200

getReasonPhrase()

Return the HTTP reason phrase associated with the status code. EG. "OK"

isJson()

Returns true if this is a JSON response.

toArray()

Converts a JSON response to an array and returns the array.

toObject()

Converts a JSON response to an ArrayObject

ArrayObject

Every Response object has all of the methods and functionality of the ArrayObject class from the rexlabs\array-object package.

This means based on the following response payload:

You can perform the following functions:

You can also call:

Config

Set default config for all client's (defaults to [])

Set config for this client (values will override / merge with default)

Default Logger

Set the default logger used by all clients that don't provide one.
Must implement LoggerInterface (defaults to NullLogger)

Log Curl

Log the curl string for all requests (requires a logger set)

Guzzle config

Set the config passed to the underlying GuzzleClient

Tests

To run tests:

To run coverage report:

Coverage report is output to ./tests/report/index.html

Extending

Hyper allows extension for custom clients by:

• Storing separate instances for each subclass of Hyper for static use
  • Static use of MyHyperSubclass will return the correct instance created by MyHyperSubclass
  • Static use of Hyper will return the correct instance created by Hyper
• Override protected static function makeClient to customise client class (eg replace new Client with new MyClient)
• Override protected static function makeConfig to customise default client config
• Override protected static function makeGuzzleConfig to customise default guzzle client
• Override protected static function getBaseUri to provide a default base_uri to the client

Contributing

Contributions are welcome, please submit a pull-request or create an issue. Your submitted code should be formatted using PSR-1/PSR-2 standards.

About

• Author: Jodie Dunlop
• License: MIT
• Copyright (c) 2018 Rex Software Pty Ltd