===============
Client Handlers
===============

Client handlers accept a request array and return a future response array that
can be used synchronously as an array or asynchronously using a promise.

Built-In Handlers
-----------------

RingPHP comes with three built-in client handlers.

Stream Handler
~~~~~~~~~~~~~~

The ``GuzzleHttp\Ring\Client\StreamHandler`` uses PHP's
`http stream wrapper <http://php.net/manual/en/wrappers.http.php>`_ to send
requests.

.. note::

    This handler cannot send requests concurrently.

You can provide an associative array of custom stream context options to the
StreamHandler using the ``stream_context`` key of the ``client`` request
option.

.. code-block:: php

    use GuzzleHttp\Ring\Client\StreamHandler;

    $response = $handler([
        'http_method' => 'GET',
        'uri' => '/',
        'headers' => ['host' => ['httpbin.org']],
        'client' => [
            'stream_context' => [
                'http' => [
                    'request_fulluri' => true,
                    'method' => 'HEAD'
                ],
                'socket' => [
                    'bindto' => '127.0.0.1:0'
                ],
                'ssl' => [
                    'verify_peer' => false
                ]
            ]
        ]
    ]);

    // Even though it's already completed, you can still use a promise
    $response->then(function ($response) {
        echo $response['status']; // 200
    });

    // Or access the response using the future interface
    echo $response['status']; // 200

cURL Handler
~~~~~~~~~~~~

The ``GuzzleHttp\Ring\Client\CurlHandler`` can be used with PHP 5.5+ to send
requests using cURL easy handles. This handler is great for sending requests
one at a time because the execute and select loop is implemented in C code
which executes faster and consumes less memory than using PHP's
``curl_multi_*`` interface.

.. note::

    This handler cannot send requests concurrently.

When using the CurlHandler, custom curl options can be specified as an
associative array of `cURL option constants <http://php.net/manual/en/curl.constants.php>`_
mapping to values in the ``client`` option of a requst using the **curl** key.

.. code-block:: php

    use GuzzleHttp\Ring\Client\CurlHandler;

    $handler = new CurlHandler();

    $request = [
        'http_method' => 'GET',
        'headers'     => ['host' => [Server::$host]],
        'client'      => ['curl' => [CURLOPT_LOW_SPEED_LIMIT => 10]]
    ];

    $response = $handler($request);

    // The response can be used directly as an array.
    echo $response['status']; // 200

    // Or, it can be used as a promise (that has already fulfilled).
    $response->then(function ($response) {
        echo $response['status']; // 200
    });

cURL Multi Handler
~~~~~~~~~~~~~~~~~~

The ``GuzzleHttp\Ring\Client\CurlMultiHandler`` transfers requests using
cURL's `multi API <http://curl.haxx.se/libcurl/c/libcurl-multi.html>`_. The
``CurlMultiHandler`` is great for sending requests concurrently.

.. code-block:: php

    use GuzzleHttp\Ring\Client\CurlMultiHandler;

    $handler = new CurlMultiHandler();

    $request = [
        'http_method' => 'GET',
        'headers'     => ['host' => [Server::$host]]
    ];

    // this call returns a future array immediately.
    $response = $handler($request);

    // Ideally, you should use the promise API to not block.
    $response
        ->then(function ($response) {
            // Got the response at some point in the future
            echo $response['status']; // 200
            // Don't break the chain
            return $response;
        })->then(function ($response) {
            // ...
        });

    // If you really need to block, then you can use the response as an
    // associative array. This will block until it has completed.
    echo $response['status']; // 200

Just like the ``CurlHandler``, the ``CurlMultiHandler`` accepts custom curl
option in the ``curl`` key of the ``client`` request option.

Mock Handler
~~~~~~~~~~~~

The ``GuzzleHttp\Ring\Client\MockHandler`` is used to return mock responses.
When constructed, the handler can be configured to return the same response
array over and over, a future response, or a the evaluation of a callback
function.

.. code-block:: php

    use GuzzleHttp\Ring\Client\MockHandler;

    // Return a canned response.
    $mock = new MockHandler(['status' => 200]);
    $response = $mock([]);
    assert(200 == $response['status']);
    assert([] == $response['headers']);

Implementing Handlers
---------------------

Client handlers are just PHP callables (functions or classes that have the
``__invoke`` magic method). The callable accepts a request array and MUST
return an instance of ``GuzzleHttp\Ring\Future\FutureArrayInterface`` so that
the response can be used by both blocking and non-blocking consumers.

Handlers need to follow a few simple rules:

1. Do not throw exceptions. If an error is encountered, return an array that
   contains the ``error`` key that maps to an ``\Exception`` value.
2. If the request has a ``delay`` client option, then the handler should only
   send the request after the specified delay time in seconds. Blocking
   handlers may find it convenient to just let the
   ``GuzzleHttp\Ring\Core::doSleep($request)`` function handle this for them.
3. Always return an instance of ``GuzzleHttp\Ring\Future\FutureArrayInterface``.
4. Complete any outstanding requests when the handler is destructed.