xref: /plugin/elasticsearch/vendor/guzzlehttp/ringphp/docs/spec.rst

=============
Specification
=============

RingPHP applications consist of handlers, requests, responses, and
middleware.

Handlers
--------

Handlers are implemented as a PHP ``callable`` that accept a request array
and return a response array (``GuzzleHttp\Ring\Future\FutureArrayInterface``).

For example:

.. code-block:: php

    use GuzzleHttp\Ring\Future\CompletedFutureArray;

    $mockHandler = function (array $request) {
        return new CompletedFutureArray([
            'status'  => 200,
            'headers' => ['X-Foo' => ['Bar']],
            'body'    => 'Hello!'
         ]);
    };

This handler returns the same response each time it is invoked. All RingPHP
handlers must return a ``GuzzleHttp\Ring\Future\FutureArrayInterface``. Use
``GuzzleHttp\Ring\Future\CompletedFutureArray`` when returning a response that
has already completed.

Requests
--------

A request array is a PHP associative array that contains the configuration
settings need to send a request.

.. code-block:: php

    $request = [
        'http_method' => 'GET',
        'scheme'      => 'http',
        'uri'         => '/',
        'body'        => 'hello!',
        'client'      => ['timeout' => 1.0],
        'headers'     => [
            'host'  => ['httpbin.org'],
            'X-Foo' => ['baz', 'bar']
        ]
    ];

The request array contains the following key value pairs:

request_method
    (string, required) The HTTP request method, must be all caps corresponding
    to a HTTP request method, such as ``GET`` or ``POST``.

scheme
    (string) The transport protocol, must be one of ``http`` or ``https``.
    Defaults to ``http``.

uri
    (string, required) The request URI excluding the query string. Must
    start with "/".

query_string
    (string) The query string, if present (e.g., ``foo=bar``).

version
    (string) HTTP protocol version. Defaults to ``1.1``.

headers
    (required, array) Associative array of headers. Each key represents the
    header name. Each value contains an array of strings where each entry of
    the array SHOULD be sent over the wire on a separate header line.

body
    (string, fopen resource, ``Iterator``, ``GuzzleHttp\Stream\StreamInterface``)
    The body of the request, if present. Can be a string, resource returned
    from fopen, an ``Iterator`` that yields chunks of data, an object that
    implemented ``__toString``, or a ``GuzzleHttp\Stream\StreamInterface``.

future
    (bool, string) Controls the asynchronous behavior of a response.

    Set to ``true`` or omit the ``future`` option to *request* that a request
    will be completed asynchronously. Keep in mind that your request might not
    necessarily be completed asynchronously based on the handler you are using.
    Set the ``future`` option to ``false`` to request that a synchronous
    response be provided.

    You can provide a string value to specify fine-tuned future behaviors that
    may be specific to the underlying handlers you are using. There are,
    however, some common future options that handlers should implement if
    possible.

    lazy
        Requests that the handler does not open and send the request
        immediately, but rather only opens and sends the request once the
        future is dereferenced. This option is often useful for sending a large
        number of requests concurrently to allow handlers to take better
        advantage of non-blocking transfers by first building up a pool of
        requests.

    If an handler does not implement or understand a provided string value,
    then the request MUST be treated as if the user provided ``true`` rather
    than the string value.

    Future responses created by asynchronous handlers MUST attempt to complete
    any outstanding future responses when they are destructed. Asynchronous
    handlers MAY choose to automatically complete responses when the number
    of outstanding requests reaches an handler-specific threshold.

Client Specific Options
~~~~~~~~~~~~~~~~~~~~~~~

The following options are only used in ring client handlers.

.. _client-options:

client
    (array) Associative array of client specific transfer options. The
    ``client`` request key value pair can contain the following keys:

    cert
        (string, array) Set to a string to specify the path to a file
        containing a PEM formatted SSL client side certificate. If a password
        is required, then set ``cert`` to an array containing the path to the
        PEM file in the first array element followed by the certificate
        password in the second array element.

    connect_timeout
        (float) Float describing the number of seconds to wait while trying to
        connect to a server. Use ``0`` to wait indefinitely (the default
        behavior).

    debug
        (bool, fopen() resource) Set to true or set to a PHP stream returned by
        fopen() to enable debug output with the handler used to send a request.
        If set to ``true``, the output is written to PHP's STDOUT. If a PHP
        ``fopen`` resource handle is provided, the output is written to the
        stream.

        "Debug output" is handler specific: different handlers will yield
        different output and various various level of detail. For example, when
        using cURL to transfer requests, cURL's `CURLOPT_VERBOSE <http://curl.haxx.se/libcurl/c/CURLOPT_VERBOSE.html>`_
        will be used. When using the PHP stream wrapper, `stream notifications <http://php.net/manual/en/function.stream-notification-callback.php>`_
        will be emitted.

    decode_content
        (bool) Specify whether or not ``Content-Encoding`` responses
        (gzip, deflate, etc.) are automatically decoded. Set to ``true`` to
        automatically decode encoded responses. Set to ``false`` to not decode
        responses. By default, content is *not* decoded automatically.

    delay
        (int) The number of milliseconds to delay before sending the request.
        This is often used for delaying before retrying a request. Handlers
        SHOULD implement this if possible, but it is not a strict requirement.

    progress
        (function) Defines a function to invoke when transfer progress is made.
        The function accepts the following arguments:

        1. The total number of bytes expected to be downloaded
        2. The number of bytes downloaded so far
        3. The number of bytes expected to be uploaded
        4. The number of bytes uploaded so far

    proxy
        (string, array) Pass a string to specify an HTTP proxy, or an
        associative array to specify different proxies for different protocols
        where the scheme is the key and the value is the proxy address.

        .. code-block:: php

            $request = [
                'http_method' => 'GET',
                'headers'     => ['host' => ['httpbin.org']],
                'client'      => [
                    // Use different proxies for different URI schemes.
                    'proxy' => [
                        'http'  => 'http://proxy.example.com:5100',
                        'https' => 'https://proxy.example.com:6100'
                    ]
                ]
            ];

    ssl_key
        (string, array) Specify the path to a file containing a private SSL key
        in PEM format. If a password is required, then set to an array
        containing the path to the SSL key in the first array element followed
        by the password required for the certificate in the second element.

    save_to
        (string, fopen resource, ``GuzzleHttp\Stream\StreamInterface``)
        Specifies where the body of the response is downloaded. Pass a string to
        open a local file on disk and save the output to the file. Pass an fopen
        resource to save the output to a PHP stream resource. Pass a
        ``GuzzleHttp\Stream\StreamInterface`` to save the output to a Guzzle
        StreamInterface. Omitting this option will typically save the body of a
        response to a PHP temp stream.

    stream
        (bool) Set to true to stream a response rather than download it all
        up-front. This option will only be utilized when the corresponding
        handler supports it.

    timeout
        (float) Float describing the timeout of the request in seconds. Use 0 to
        wait indefinitely (the default behavior).

    verify
        (bool, string) Describes the SSL certificate verification behavior of a
        request. Set to true to enable SSL certificate verification using the
        system CA bundle when available (the default). Set to false to disable
        certificate verification (this is insecure!). Set to a string to provide
        the path to a CA bundle on disk to enable verification using a custom
        certificate.

    version
        (string) HTTP protocol version to use with the request.

Server Specific Options
~~~~~~~~~~~~~~~~~~~~~~~

The following options are only used in ring server handlers.

server_port
    (integer) The port on which the request is being handled. This is only
    used with ring servers, and is required.

server_name
    (string) The resolved server name, or the server IP address. Required when
    using a Ring server.

remote_addr
    (string) The IP address of the client or the last proxy that sent the
    request. Required when using a Ring server.

Responses
---------

A response is an array-like object that implements
``GuzzleHttp\Ring\Future\FutureArrayInterface``. Responses contain the
following key value pairs:

body
    (string, fopen resource, ``Iterator``, ``GuzzleHttp\Stream\StreamInterface``)
    The body of the response, if present. Can be a string, resource returned
    from fopen, an ``Iterator`` that yields chunks of data, an object that
    implemented ``__toString``, or a ``GuzzleHttp\Stream\StreamInterface``.

effective_url
    (string) The URL that returned the resulting response.

error
    (``\Exception``) Contains an exception describing any errors that were
    encountered during the transfer.

headers
    (Required, array) Associative array of headers. Each key represents the
    header name. Each value contains an array of strings where each entry of
    the array is a header line. The headers array MAY be an empty array in the
    event an error occurred before a response was received.

reason
    (string) Optional reason phrase. This option should be provided when the
    reason phrase does not match the typical reason phrase associated with the
    ``status`` code. See `RFC 7231 <http://tools.ietf.org/html/rfc7231#section-6.1>`_
    for a list of HTTP reason phrases mapped to status codes.

status
    (Required, integer) The HTTP status code. The status code MAY be set to
    ``null`` in the event an error occurred before a response was received
    (e.g., a networking error).

transfer_stats
    (array) Provides an associative array of arbitrary transfer statistics if
    provided by the underlying handler.

version
    (string) HTTP protocol version. Defaults to ``1.1``.

Middleware
----------

Ring middleware augments the functionality of handlers by invoking them in the
process of generating responses. Middleware is typically implemented as a
higher-order function that takes one or more handlers as arguments followed by
an optional associative array of options as the last argument, returning a new
handler with the desired compound behavior.

Here's an example of a middleware that adds a Content-Type header to each
request.

.. code-block:: php

    use GuzzleHttp\Ring\Client\CurlHandler;
    use GuzzleHttp\Ring\Core;

    $contentTypeHandler = function(callable $handler, $contentType) {
        return function (array $request) use ($handler, $contentType) {
            return $handler(Core::setHeader('Content-Type', $contentType));
        };
    };

    $baseHandler = new CurlHandler();
    $wrappedHandler = $contentTypeHandler($baseHandler, 'text/html');
    $response = $wrappedHandler([/** request hash **/]);