rexlabs / hyper-http
HTTP client for PHP
Installs: 78 698
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 4
Forks: 0
Open Issues: 0
Requires
- php: >=7.4 <8.3
- guzzlehttp/guzzle: ^7.0
- guzzlehttp/psr7: ^2.4.0
- psr/log: ^1.0 || ^2.0 || ^3.0
- rexlabs/array-object: ^3.0
- rexlabs/cuzzle: ^3.0
- rexlabs/utility-belt: ^4.0
- rtheunissen/guzzle-log-middleware: ^1.0
Requires (Dev)
- phpunit/phpunit: ^9
README
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
<?php use Rexlabs\HyperHttp\Hyper; $response = Hyper::get('http://openlibrary.org/subjects/love.json'); // The first book for 'love' is: Wuthering Heights echo "The first book for '{$response->name}' is: {$response->works->first()->title}\n"; echo "Total works: {$response->works->count()} books\n";
Installation
To install in your project:
composer require rexlabs/hyper-http
Examples
The RESTful methods all return a Response
object which makes interacting with responses simple.
Example: Using static methods
<?php use Rexlabs\HyperHttp\Hyper; $response = Hyper::get('https://example.com/url'); echo 'Status Code: '.$response->getStatusCode()."\n"; echo (string)$response; // Output the response body
Example: Working with a JSON API
Since responses mixin ArrayObject you can easily fetch and manipulate values from the response:
<?php use Rexlabs\HyperHttp\Hyper; // Fetch historical price via CryptoCompare's public API for Ethereum $response = Hyper::get('https://min-api.cryptocompare.com/data/pricehistorical', [ 'fsym' => 'ETH', 'tsyms' => 'BTC,USD', 'ts' => '1452680400', ]); // Output prices printf("ETH->USD: %s\n", $response->get('ETH.USD')); printf("ETH->BTC: %s\n", $response->get('ETH.BTC'));
Example: Set global headers and pass in a logger
Use make()
to simplify instantiation and then setup the object
for future requests:
<?php use Rexlabs\HyperHttp\Hyper; use Rexlabs\Logger\CustomLogger; $hyper = Hyper::make() ->setBaseUri('http://example.com/api/v1') ->setHeader('X-App-Identity', 'Some App') ->setHeader('X-Correlation-Id', '12345') ->setLogger(new CustomLogger);
$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:
<?php use Rexlabs\HyperHttp\Client; use GuzzleHttp\Client as GuzzleClient; use Psr\Log\NullLogger; $hyper = new Client(new GuzzleClient(), new NullLogger(), [ 'base_uri' => 'http://example.com/api/v1', 'headers' => [ 'X-App-Identity' => 'Some App', ], ]); $response = $hyper->get('/messages');
Example: Dumping a cURL request
You can easily generate a cURL request for running from the command-line to reproduce your last request:
<?php use Rexlabs\HyperHttp\Hyper; echo Hyper::get('https://example.com/api/v1/resources') ->getCurlRequest();
Output:
curl \ 'https://min-api.cryptocompare.com/data/pricehistorical?fsym=ETH&tsyms=BTC%2CUSD&ts=1452680400&extraParams=your_app_name' \ -H 'Content-Type: application/json' -H 'Accept: application/json'
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:
$response = Hyper::get('https://example.com', ['sort' => 'latest'], ['X-Greeting' => 'Hello!']); $response = $hyper->get('/v1/people');
$uri
is a string or aUri
. 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:
$response = Hyper::post('https://example.com/fruit', 'apples'); $response = $hyper->post('/v1/people', ['name' => 'Bob', 'age' => 25]);
$uri
is a string or aUri
. 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:
$response = Hyper::put('https://example.com/fruit', 'apples'); $response = $hyper->put('/v1/people', ['name' => 'Bob', 'age' => 25]);
$uri
is a string or aUri
. 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:
$response = Hyper::patch('https://example.com/fruit', 'apples'); $response = $hyper->patch('/v1/people', ['name' => 'Bob', 'age' => 25]);
$uri
is a string or aUri
. 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:
$response = Hyper::delete('https://example.com/fruit', 'apples'); $response = $hyper->delete('/v1/people/1');
$uri
is a string or aUri
. 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.
// Statically $response = Hyper::call('MOVE', 'myfile1234', ['new_location' => 'some_folder']); // Http method verbs may also be invoked via method name $response = Hyper::move('myfile1234', ['new_location' => 'some_folder']); $response = Hyper::somethingelse(...); // Via object $response = $hyper->call('MOVE', 'myfile1234', ['new_location' => 'some_folder']);
$method
is the HTTP verb. Eg.GET
or something not part of the standard.$uri
is a string or aUri
. 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:
{ "books": [ { "id": 1, "title": "1984", "author": "George Orwell" }, { "id": 2, "title": "Pride and Prejudice", "author": "Jane Austen" } ] }
You can perform the following functions:
$response->books; // Instance of ArrayObject $response->books->pluckArray('author'); // array [ 'George Orwell', 'Jane Austen' ] $response->pluckArray('books.author'); // array [ 'George Orwell', 'Jane Austen' ] $response->books->count(); // 2 $response->books->isCollection(); // true $response->books[0]; // Instance of ArrayObject $response->books[0]->isCollection(); // false $response->books[0]->id; // 1 $response->get('books.1.title'); // "Pride and Prejudice" foreach ($response->books as $book) { echo "{$book->title} by {$book->author}\n"; }
You can also call:
$obj = $response->toObject(); // Instance of Arraybject
Config
Set default config for all client's (defaults to [])
Hyper::setDefaultConfig($config);
Set config for this client (values will override / merge with default)
$client = Hyper::make($config);
Default Logger
Set the default logger used by all clients that don't provide one.
Must implement LoggerInterface
(defaults to NullLogger
)
Hyper::setDefaultLogger($logger);
Log Curl
Log the curl string for all requests (requires a logger set)
$config = [ 'log_curl' => true, ];
Guzzle config
Set the config passed to the underlying GuzzleClient
$config = [ 'guzzle' => [ 'verify' => false, ], ]; // Set for all clients Hyper::setDefaultConfig($config); // Set for one client $client = Hyper::make($config);
Tests
To run tests:
composer tests
To run coverage report:
composer coverage
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 byMyHyperSubclass
- Static use of
Hyper
will return the correct instance created byHyper
- Static use of
- Override
protected static function makeClient
to customise client class (eg replacenew Client
withnew 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