This package offers an easy to use set of functions to send HTTP requests in PHP.
- Easy to use GET, POST, PUT, PATCH and DELETE functions (see usage)
- Send optional data and headers with your requests
- Use optional basic authentication with your requests
- Optional caching of GET and POST responses
- Laravel 5 ServiceProvider included!
Install this package through Composer:
"require": {
"codezero/courier": "2.*"
}
At this point there is only one Courier implementation: CurlCourier
, which uses codezero-be/curl and the PHP cURL extension behind the scenes.
use CodeZero\Courier\CurlCourier;
$courier = new CurlCourier();
After installing, update your config/app.php
file to include a reference to this package's service provider in the providers array:
'providers' => [
'CodeZero\Courier\CourierServiceProvider'
]
Inject the Courier instance into your own class:
use CodeZero\Courier\Courier; //=> The interface
class MyClass {
private $courier;
public function __construct(Courier $courier)
{
$this->courier = $courier;
}
}
Laravel will then find the Courier
class automatically if you registered the service provider.
Or you can inject an instance manually: $myClass = new MyClass($courier);
$url = 'http://my.site/api';
$data = ['do' => 'something', 'with' => 'this']; //=> Optional
$headers = ['Some Header' => 'Some Value']; //=> Optional
Optional number of minutes to cache the request/response. Until it expires Courier will not actually hit the requested URL, but return a cached response! If you use Laravel then Laravel's Cache
will be used. If not then phpFastCache
is used.
$cacheMinutes = 30; //=> Default = 0 (no caching)
If the target server sends a HTTP error response >= 400, a CodeZero\Courier\Exceptions\HttpException
will be thrown.
Your class can also implement the CodeZero\Courier\HttpExceptionHandler
interface and add a handleHttpException
method. If you pass Courier a reference to your class, then no exception will be thrown. Instead, the HttpException
will be passed to your handleHttpException
method, so you can throw your own exception or return any value back to the original caller.
$handler = $this; //=> A reference to your class (optional)
$response = $this->courier->get($url, $data, $headers, $cacheMinutes, $handler);
$response = $this->courier->post($url, $data, $headers, $cacheMinutes, $handler);
$response = $this->courier->put($url, $data, $headers, $handler);
$response = $this->courier->patch($url, $data, $headers, $handler);
$response = $this->courier->delete($url, $data, $headers, $handler);
All of these methods will return an instance of the CodeZero\Courier\Response
class.
$body = $response->getBody();
$httpCode = $response->getHttpCode(); //=> "200"
$httpMessage = $response->getHttpMessage(); //=> "OK"
$responseType = $response->getResponseType(); //=> "application/json"
$responseCharset = $response->getResponseCharset(); //=> "UTF-8"
You can convert a JSON or serialized response to an associative array or to an array of generic PHP objects. If you are sending API requests, chances are high that you get application/json
data in return. The Flickr API php_serial
responses are of type application/binary
and serializable.
To convert this data just run:
$array = $response->toArray();
echo $array[0]['some']['nested']['key'];
$objects = $response->toObjects();
echo $objects[0]->some->nested->key;
If for some reason the conversion fails, a CodeZero\Courier\Exceptions\ResponseConversionException
will be thrown.
To enable caching, there are 2 conditions:
- Courier needs to be instantiated with the
CodeZero\Courier\Cache\Cache
class and a valid implementation of theCodeZero\Courier\Cache\CacheManager
has to be provided to this dependency. This is done automatically. - Caching minutes need to be greater than zero (default: 0)
Each request can have a different cache time. Just specify it in the method call:
$this->courier->get($url, $data, $headers, $cacheMinutes);
$this->courier->forgetCache();
If you require the use of basic authentication, you can enable this before sending the request:
$this->courier->setBasicAuthentication('username', 'password');
You can also undo this:
$this->courier->unsetBasicAuthentication();
A CodeZero\Courier\Exceptions\RequestException
will be thrown, if the request could not be executed. This might be the case if your request is not properly configured (unsupported protocol, etc.).
A CodeZero\Courier\Exceptions\HttpException
will be thrown, if there was a HTTP response error >= 400. Unless you are using the handleHttpException
callback. In that case you must add this method to your class:
public function handleHttpException(HttpException $exception)
{
$errorMessage = $exception->getMessage();
$errorCode = $exception->getCode();
$response = $exception->response();
$responseBody = $response->getBody();
// If it's JSON:
$array = $response->toArray();
// throw your exception
// or return something
}
$ vendor/bin/phpspec run
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.