Download the PHP package codezero/courier without Composer

Courier - HTTP Requests Made Easy

[]() []()

This package offers an easy to use set of functions to send HTTP requests in PHP.

Features

• 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!

Installation

Install this package through Composer:

"require": {
    "codezero/courier": "2.*"
}

Implementation

Manual

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();

Laravel 5

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 Courier

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);

Send a Request

Configure a Request:

$url = 'http://my.site/api';
$data = ['do' => 'something', 'with' => 'this']; //=> Optional
$headers = ['Some Header' => 'Some Value']; //=> Optional

Enable Caching

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)

Handle Exceptions

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, so you can throw your own exception or return any value back to the original caller.

$handler = $this; //=> A reference to your class (optional)

Send the Request: (one of the following)

$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.

Read the Response

Get the Response Body

$body = $response->getBody();

Get Additional Request Info

$httpCode = $response->getHttpCode(); //=> "200"
$httpMessage = $response->getHttpMessage(); //=> "OK"
$responseType = $response->getResponseType(); //=> "application/json"
$responseCharset = $response->getResponseCharset(); //=> "UTF-8" 

Convert the Response

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.

Caching

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)

Cache Time

Each request can have a different cache time. Just specify it in the method call:

$this->courier->get($url, $data, $headers, $cacheMinutes); 

Clear Cache at Runtime:

$this->courier->forgetCache();

Basic Authentication

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();

Exceptions

Request Issues

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.).

Response Issues

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
}

Testing

$ vendor/bin/phpspec run

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.