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:

1. Courier needs to be instantiated with the CodeZero\Courier\Cache\Cache class and a valid implementation of the CodeZero\Courier\Cache\CacheManager has to be provided to this dependency. This is done automatically.
2. 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.