===========================
Request and response bodies
===========================

`Entity body <http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html>`_ is the term used for the body of an HTTP
message. The entity body of requests and responses is inherently a
`PHP stream <http://php.net/manual/en/book.stream.php>`_ in Guzzle. The body of the request can be either a string or
a PHP stream which are converted into a ``Guzzle\Http\EntityBody`` object using its factory method. When using a
string, the entity body is stored in a `temp PHP stream <http://www.php.net/manual/en/wrappers.php.php>`_. The use of
temp PHP streams helps to protect your application from running out of memory when sending or receiving large entity
bodies in your messages. When more than 2MB of data is stored in a temp stream, it automatically stores the data on
disk rather than in memory.

EntityBody objects provide a great deal of functionality: compression, decompression, calculate the Content-MD5,
calculate the Content-Length (when the resource is repeatable), guessing the Content-Type, and more. Guzzle doesn't
need to load an entire entity body into a string when sending or retrieving data; entity bodies are streamed when
being uploaded and downloaded.

Here's an example of gzip compressing a text file then sending the file to a URL:

.. code-block:: php

    use Guzzle\Http\EntityBody;

    $body = EntityBody::factory(fopen('/path/to/file.txt', 'r+'));
    echo $body->read(1024);
    $body->seek(0, SEEK_END);
    $body->write('foo');
    echo $body->ftell();
    $body->rewind();

    // Send a request using the body
    $response = $client->put('http://localhost:8080/uploads', null, $body)->send();

The body of the request can be specified in the ``Client::put()`` or ``Client::post()``  method, or, you can specify
the body of the request by calling the ``setBody()`` method of any
``Guzzle\Http\Message\EntityEnclosingRequestInterface`` object.

Compression
-----------

You can compress the contents of an EntityBody object using the ``compress()`` method. The compress method accepts a
filter that must match to one of the supported
`PHP stream filters <http://www.php.net/manual/en/filters.compression.php>`_ on your system (e.g. `zlib.deflate`,
``bzip2.compress``, etc). Compressing an entity body will stream the entire entity body through a stream compression
filter into a temporary PHP stream. You can uncompress an entity body using the ``uncompress()`` method and passing
the PHP stream filter to use when decompressing the stream (e.g. ``zlib.inflate``).

.. code-block:: php

    use Guzzle\Http\EntityBody;

    $body = EntityBody::factory(fopen('/tmp/test.txt', 'r+'));
    echo $body->getSize();
    // >>> 1048576

    // Compress using the default zlib.deflate filter
    $body->compress();
    echo $body->getSize();
    // >>> 314572

    // Decompress the stream
    $body->uncompress();
    echo $body->getSize();
    // >>> 1048576

Decorators
----------

Guzzle provides several EntityBody decorators that can be used to add functionality to an EntityBody at runtime.

IoEmittingEntityBody
~~~~~~~~~~~~~~~~~~~~

This decorator will emit events when data is read from a stream or written to a stream. Add an event subscriber to the
entity body's ``body.read`` or ``body.write`` methods to receive notifications when data data is transferred.

.. code-block:: php

    use Guzzle\Common\Event;
    use Guzzle\Http\EntityBody;
    use Guzzle\Http\IoEmittingEntityBody;

    $original = EntityBody::factory(fopen('/tmp/test.txt', 'r+'));
    $body = new IoEmittingEntityBody($original);

    // Listen for read events
    $body->getEventDispatcher()->addListener('body.read', function (Event $e) {
        // Grab data from the event
        $entityBody = $e['body'];
        // Amount of data retrieved from the body
        $lengthOfData = $e['length'];
        // The actual data that was read
        $data = $e['read'];
    });

    // Listen for write events
    $body->getEventDispatcher()->addListener('body.write', function (Event $e) {
        // Grab data from the event
        $entityBody = $e['body'];
        // The data that was written
        $data = $e['write'];
        // The actual amount of data that was written
        $data = $e['read'];
    });

ReadLimitEntityBody
~~~~~~~~~~~~~~~~~~~

The ReadLimitEntityBody decorator can be used to transfer a subset or slice of an existing EntityBody object. This can
be useful for breaking a large file into smaller pieces to be sent in chunks (e.g. Amazon S3's multipart upload API).

.. code-block:: php

    use Guzzle\Http\EntityBody;
    use Guzzle\Http\ReadLimitEntityBody;

    $original = EntityBody::factory(fopen('/tmp/test.txt', 'r+'));
    echo $original->getSize();
    // >>> 1048576

    // Limit the size of the body to 1024 bytes and start reading from byte 2048
    $body = new ReadLimitEntityBody($original, 1024, 2048);
    echo $body->getSize();
    // >>> 1024
    echo $body->ftell();
    // >>> 0

CachingEntityBody
~~~~~~~~~~~~~~~~~

The CachingEntityBody decorator is used to allow seeking over previously read bytes on non-seekable read streams. This
can be useful when transferring a non-seekable entity body fails due to needing to rewind the stream (for example,
resulting from a redirect). Data that is read from the remote stream will be buffered in a PHP temp stream so that
previously read bytes are cached first in memory, then on disk.

.. code-block:: php

    use Guzzle\Http\EntityBody;
    use Guzzle\Http\CachingEntityBody;

    $original = EntityBody::factory(fopen('http://www.google.com', 'r'));
    $body = new CachingEntityBody($original);

    $body->read(1024);
    echo $body->ftell();
    // >>> 1024

    $body->seek(0);
    echo $body->ftell();
    // >>> 0