Indigo HTTP Adapter
, (*1)
Provides adapters for common HTTP Client libraries., (*2)
Why an other HTTP library again?
The proposed HTTP Message PSR is going to be great....but that won't let anyone create HTTP Client agnostic packages. For example you cannot typehint for a ClientInterface. You can only operate on the same messages. The PSR Meta also mentions adapter packages as a valid approach. There are many cool adapter packages out there, but all of them implement a simple logic based on the author's need. You can consider this package as a simple Adapter providing you full control over the common fetures of the implemented HTTP Client libraries. However, it must be noted that the specific features are out of scope. For example: if you need to use Guzzle specific feature, depend on it instead., (*3)
This package also provides a simple implementation of the latest PSR interfaces., (*4)
Install
Via Composer, (*5)
``` bash
$ composer require indigophp/http-adapter, (*6)
## Usage
### Simple usage
You are free to directly use any adapters in your application.
``` php
use Indigo\Http\Adapter;
class MyAdapterAware
{
/**
* @var Adapter
*/
private $adapter;
public function __construct(Adapter $adapter)
{
$this->adapter = $adapter;
}
public function get()
{
$request = new Request;
$request->setUrl('http://foo.com');
return $this->adapter->send($request);
}
}
You can also use the client class for the most common client usage. (Guzzle is only used as an example), (*7)
``` php
use GuzzleHttp\Client as GuzzleClient;
use Indigo\Http\Adapter\Guzzle4;
use Indigo\Http\Client;, (*8)
$adapter = new Guzzle4(new GuzzleClient);
$client = new Client($adapter);, (*9)
$client->get('http://foo.com');, (*10)
### Advanced usage
For testing you can use the `Mock` adapter.
``` php
use Indigo\Http\Adapter\Mock;
use Psr\Http\Message\RequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;
// ... your testing logic
// you can directly pass the Response object to the constructor
$adapter = new Mock(function(Request $request) {
return new Response;
});
// Optionally
$adapter->setResponse(new Response);
// ... your testing logic
You can decorate your adapters with various decorators., (*11)
Event decorator
Event decorator emitts two events:, (*12)
- Before (request)
- Complete (response)
Both events receive the Adapter and the Request. The Complete event contains the Response as well., (*13)
``` php
use Indigo\Http\Adapter\Event;
use Indigo\Http\Event;, (*14)
$adapter = new Event($decoratedAdapter);, (*15)
// Optionally
// $adapter->setEmitter($emitter);, (*16)
$adapter->addListener('before', function(Event\Before $event) {
$adapter = $event->getAdapter();
$request = $event->getRequest();, (*17)
// ... do something with the adapter and the request
});, (*18)
$adapter->addListener('complete', function(Event\Complete $event) {
$adapter = $event->getAdapter();
$request = $event->getRequest();
$response = $event->getResponse();, (*19)
// ... do something with the adapter, request and the response
});, (*20)
You can also use `Subscriber`s with the `Event` adapter.
``` php
use Indigo\Http\Adapter\Event;
use Indigo\Http\Subscriber\Auth;
$adapter = new Event($decoratedAdapter);
// This will always attach authentication data to your requests
$adapter->addSubscriber(new Auth('username', 'password', Auth::BASIC));
Currently league/event is used as event backend., (*21)
Cache decorator
You can use a local cache for returned Responses. Based on cached items you can send Requests to the server with If-Modified-Since and If-None-Match (ETag header required in response) headers. If the server return with 304 status then the cached item is returned, otherwise it gets cached for future., (*22)
``` php
use Indigo\Http\Adapter\Cache;, (*23)
$adapter = new Cache($decoratedAdapter);, (*24)
// Optionally
// $adapter->setPool($pool);, (*25)
// Status: 200 OK
$response = $adapter->send($request);, (*26)
// Status: 304 Not Modified
// Returned from cache
$response = $adapter->send($request);, (*27)
Currently [Stash](http://stashphp.com) is used as cache backend.
### Exceptions
There are two main type of exceptions:
- `AdapterException`: Thrown when some sort of adapter problem occurs.
- `RequestException`: Thrown if the response itself is an error response (4xx, 5xx) or the request cannot be completed (no response returned).
## Testing
``` bash
$ phpspec run
Contributing
Please see CONTRIBUTING for details., (*28)
Credits
Inspired by
License
The MIT License (MIT). Please see License File for more information., (*29)
Wallogit.com
