.. _zend.http.client.advanced:

HTTP Client - Advanced Usage
============================

.. _zend.http.client.redirections:

HTTP Redirections
-----------------

``Zend\Http\Client`` automatically handles *HTTP* redirections, and by default will follow up to 5 redirections.
This can be changed by setting the ``maxredirects`` configuration parameter.

According to the *HTTP*/1.1 RFC, *HTTP* 301 and 302 responses should be treated by the client by resending the same
request to the specified location - using the same request method. However, most clients to not implement this and
always use a ``GET`` request when redirecting. By default, ``Zend\Http\Client`` does the same - when redirecting on
a 301 or 302 response, all ``GET`` and POST parameters are reset, and a ``GET`` request is sent to the new
location. This behavior can be changed by setting the ``strictredirects`` configuration parameter to boolean
``TRUE``:

.. _zend.http.client.redirections.example-1:

.. rubric:: Forcing RFC 2616 Strict Redirections on 301 and 302 Responses

.. code-block:: php
   :linenos:

   // Strict Redirections
   $client->setOptions(array('strictredirects' => true));

   // Non-strict Redirections
   $client->setOptions(array('strictredirects' => false));



You can always get the number of redirections done after sending a request using the ``getRedirectionsCount()`` method.

.. _zend.http.client.cookies:

Adding Cookies and Using Cookie Persistence
-------------------------------------------

``Zend\Http\Client`` provides an easy interface for adding cookies to your request, so that no direct header
modification is required. Cookies can be added using either the `addCookie()` or ``setCookies`` method.  The 
``addCookie`` method has a number of operating modes:

.. _zend.http.client.cookies.example-1:

.. rubric:: Setting Cookies Using addCookie()

.. code-block:: php
   :linenos:

    // Easy and simple: by providing a cookie name and cookie value
    $client->addCookie('flavor', 'chocolate chips');

    // By directly providing a raw cookie string (name=value)
    // Note that the value must be already URL encoded
    $client->addCookie('flavor=chocolate%20chips');

    // By providing a Zend\Http\Header\SetCookie object
    $cookie = Zend\Http\Header\SetCookie::fromString('flavor=chocolate%20chips');
    $client->addCookie($cookie);

    // Multiple cookies can be set at once by providing an
    // array of Zend\Http\Header\SetCookie objects
    $cookies = array(
        Zend\Http\Header\SetCookie::fromString('flavorOne=chocolate%20chips'),
        Zend\Http\Header\SetCookie::fromString('flavorTwo=vanilla'),
    );
    $client->addCookie($cookies);

The ``setCookies()`` method works in a similar manner, except that it requires an array
of cookie values as its only argument and also clears the cookie container before 
adding the new cookies:

.. _zend.http.client.cookies.example-2:

.. rubric:: Setting Cookies Using setCookies()

.. code-block:: php
   :linenos:

    // setCookies accepts an array of cookie values, which
    // can be in either of the following formats:
    $client->setCookies(array(

        // A raw cookie string (name=value)
        // Note that the value must be already URL encoded
        'flavor=chocolate%20chips',

        // A Zend\Http\Header\SetCookie object
        Zend\Http\Header\SetCookie::fromString('flavor=chocolate%20chips'),

    ));


For more information about ``Zend\Http\Header\SetCookie`` objects, see :ref:`this section <zend.http.header.set-cookie>`.

``Zend\Http\Client`` also provides a means for simplifying cookie stickiness - that is having the client internally store all
sent and received cookies, and resend them on subsequent requests: ``Zend\Http\Client\Cookies``. This is useful, for example when
you need to log in to a remote site first and receive and authentication or session ID cookie before sending
further requests.

.. _zend.http.client.cookies.example-3:

.. rubric:: Enabling Cookie Stickiness

.. code-block:: php
   :linenos:

   $cookies = new Zend\Http\Cookies();

   // First request: log in and start a session
   $client->setUri('http://example.com/login.php');
   $client->setParameterPost(array('user' => 'h4x0r', 'password' => 'l33t'));
   $response = $client->request('POST');
   $cookies->addCookiesFromResponse($response, $client->getUri());

   // Now we can send our next request
   $client->setUri('http://example.com/read_member_news.php');
   $client->addCookies($cookies->getMatchingCookies($client->getUri());
   $client->request('GET');

For more information about the ``Zend\Http\Client\Cookies`` class, see :ref:`this section
<zend.http.client.cookies>`.

.. _zend.http.client.custom_headers:

Setting Custom Request Headers
------------------------------

Setting custom headers is performed by first fetching the header container from the client's 
``Zend\Http\Request`` object.  This method is quite diverse and can be used in several ways, 
as the following example shows:

.. _zend.http.client.custom_headers.example-1:

.. rubric:: Setting A Single Custom Request Header

.. code-block:: php
    :linenos:

    // Fetch the container
    $headers = $client->getRequest()->getHeaders();

    // Setting a single header. Will not overwrite any 
    // previously-added headers of the same name.
    $client->addHeaderLine('Host', 'www.example.com');

    // Another way of doing the exact same thing
    $client->addHeaderLine('Host: www.example.com');

    // Another way of doing the exact same thing using
    // the provided Zend\Http\Header class
    $client->addHeader(Zend\Http\Header\Host::fromString('Host: www.example.com'));

    // You can also add multiple headers at once by passing an
    // array to addHeaders using any of the formats below:
    $client->addHeaders(array(
        // Zend\Http\Header\* object
        Zend\Http\Header\Host::fromString('Host: www.example.com'),

        // Header name as array key, header value as array key value
        'Cookie' => 'PHPSESSID=1234567890abcdef1234567890abcdef',

        // Raw header string
        'Cookie: language=he',
    ));


``Zend\Http\Client`` also provides a convenience method for setting request headers, ``setHeaders``.
This method will create a new header container, add the specified headers and then store the new
header container in it's ``Zend\Http\Request`` object.  As a consequence, any pre-existing headers
will be erased.

.. _zend.http.client.custom_headers.example-2:

.. rubric:: Setting Multiple Custom Request Headers

.. code-block:: php
    :linenos:

    // Setting multiple headers.  Will remove all existing
    // headers and add new ones to the Request header container
    $client->setHeaders(array(
     Zend\Http\Header\Host::fromString('Host: www.example.com'),
     'Accept-encoding' => 'gzip,deflate',
     'X-Powered-By: Zend Framework'
    ));


.. _zend.http.client.file_uploads:

File Uploads
------------

You can upload files through *HTTP* using the setFileUpload method. This method takes a file name as the first
parameter, a form name as the second parameter, and data as a third optional parameter. If the third data parameter
is ``NULL``, the first file name parameter is considered to be a real file on disk, and ``Zend\Http\Client`` will
try to read this file and upload it. If the data parameter is not ``NULL``, the first file name parameter will be
sent as the file name, but no actual file needs to exist on the disk. The second form name parameter is always
required, and is equivalent to the "name" attribute of an >input< tag, if the file was to be uploaded through an
*HTML* form. A fourth optional parameter provides the file's content-type. If not specified, and
``Zend\Http\Client`` reads the file from the disk, the ``mime_content_type`` function will be used to guess the file's
content type, if it is available. In any case, the default MIME type will be application/octet-stream.


.. _zend.http.client.file_uploads.example-1:

.. rubric:: Using setFileUpload to Upload Files

.. code-block:: php
    :linenos:

    // Uploading arbitrary data as a file
    $text = 'this is some plain text';
    $client->setFileUpload('some_text.txt', 'upload', $text, 'text/plain');

    // Uploading an existing file
    $client->setFileUpload('/tmp/Backup.tar.gz', 'bufile');

    // Send the files
    $client->setMethod('POST');
    $client->send();

In the first example, the ``$text`` variable is uploaded and will be available as ``$_FILES['upload']`` on the server side.
In the second example, the existing file ``/tmp/Backup.tar.gz`` is uploaded to the server and will be available as
``$_FILES['bufile']``. The content type will be guessed automatically if possible - and if not, the content type will
be set to 'application/octet-stream'.

.. note::

   **Uploading files**

   When uploading files, the *HTTP* request content-type is automatically set to multipart/form-data. Keep in mind
   that you must send a POST or PUT request in order to upload files. Most servers will ignore the request body on
   other request methods.

.. _zend.http.client.raw_post_data:

Sending Raw POST Data
---------------------

You can use a ``Zend\Http\Client`` to send raw POST data using the ``setRawBody()`` method. This method takes one
parameter: the data to send in the request body. When sending raw POST data, it is advisable to also set the
encoding type using ``setEncType()``.


.. _zend.http.client.raw_post_data.example-1:

.. rubric:: Sending Raw POST Data

.. code-block:: php
    :linenos:

    $xml = '<book>' .
        '  <title>Islands in the Stream</title>' .
        '  <author>Ernest Hemingway</author>' .
        '  <year>1970</year>' .
        '</book>';
    $client->setMethod('POST');
    $client->setRawBody($xml);
    $client->setEncType('text/xml');
    $client->send();

The data should be available on the server side through *PHP*'s ``$HTTP_RAW_POST_DATA`` variable or through the
``php://input`` stream.

.. note::

   **Using raw POST data**

   Setting raw POST data for a request will override any POST parameters or file uploads. You should not try to use
   both on the same request. Keep in mind that most servers will ignore the request body unless you send a POST
   request.

.. _zend.http.client.http_authentication:

HTTP Authentication
-------------------

Currently, ``Zend\Http\Client`` only supports basic *HTTP* authentication. This feature is utilized using the
``setAuth()`` method, or by specifying a username and a password in the URI. The ``setAuth()`` method takes 3
parameters: The user name, the password and an optional authentication type parameter. As mentioned, currently only
basic authentication is supported (digest authentication support is planned).


.. _zend.http.client.http_authentication.example-1:

.. rubric:: Setting HTTP Authentication User and Password

.. code-block:: php
    :linenos:

    // Using basic authentication
    $client->setAuth('shahar', 'myPassword!', Zend\Http\Client::AUTH_BASIC);

    // Since basic auth is default, you can just do this:
    $client->setAuth('shahar', 'myPassword!');

    // You can also specify username and password in the URI
    $client->setUri('http://christer:secret@example.com');



.. _zend.http.client.multiple_requests:

Sending Multiple Requests With the Same Client
----------------------------------------------

``Zend\Http\Client`` was also designed specifically to handle several consecutive requests with the same object.
This is useful in cases where a script requires data to be fetched from several places, or when accessing a
specific *HTTP* resource requires logging in and obtaining a session cookie, for example.

When performing several requests to the same host, it is highly recommended to enable the 'keepalive' configuration
flag. This way, if the server supports keep-alive connections, the connection to the server will only be closed
once all requests are done and the Client object is destroyed. This prevents the overhead of opening and closing
*TCP* connections to the server.

When you perform several requests with the same client, but want to make sure all the request-specific parameters
are cleared, you should use the ``resetParameters()`` method. This ensures that GET and POST parameters, request
body and headers are reset and are not reused in the next request.

.. note::

   **Resetting parameters**

   Note that cookies are not reset by default when the ``resetParameters()`` method is used.
   To clean all cookies as well, use ``resetParameters(true)``, or call ``clearCookies()`` after
   calling ``resetParameters()``.

Another feature designed specifically for consecutive requests is the ``Zend\Http\Client\Cookies`` object. 
This "Cookie Jar" allow you to save cookies set by the server in a request, and send them back on consecutive
requests transparently. This allows, for example, going through an authentication request before sending 
the actual data-fetching request.

If your application requires one authentication request per user, and consecutive requests might be performed in
more than one script in your application, it might be a good idea to store the Cookies object in the user's
session. This way, you will only need to authenticate the user once every session.

.. _zend.http.client.multiple_requests.example-1:

.. rubric:: Performing consecutive requests with one client

.. code-block:: php
   :linenos:

   // First, instantiate the client
   $client = new Zend\Http\Client('http://www.example.com/fetchdata.php', array(
       'keepalive' => true
   ));

   // Do we have the cookies stored in our session?
   if (isset($_SESSION['cookiejar']) &&
       $_SESSION['cookiejar'] instanceof Zend\Http\Client\Cookies) {

       $cookieJar = $_SESSION['cookiejar'];
   } else {
       // If we don't, authenticate and store cookies
       $client->setUri('http://www.example.com/login.php');
       $client->setParameterPost(array(
           'user' => 'shahar',
           'pass' => 'somesecret'
       ));
       $response = $client->setMethod('POST')->send();
       $cookieJar = Zend\Http\Client\Cookies::fromResponse($response);

       // Now, clear parameters and set the URI to the original one
       // (note that the cookies that were set by the server are now
       // stored in the jar)
       $client->resetParameters();
       $client->setUri('http://www.example.com/fetchdata.php');
   }

   // Add the cookies to the new request
   $client->setCookies($cookieJar->getMatchingCookies($client->getUri()));
   $response = $client->setMethod('GET')->send();

   // Store cookies in session, for next page
   $_SESSION['cookiejar'] = $cookieJar;

.. _zend.http.client.streaming:

Data Streaming
--------------

By default, ``Zend\Http\Client`` accepts and returns data as *PHP* strings. However, in many cases there are big
files to be received, thus keeping them in memory might be unnecessary or too expensive. For these cases,
``Zend\Http\Client`` supports writing data to files (streams).

In order to receive data from the server as stream, use ``setStream()``. Optional argument specifies the filename
where the data will be stored. If the argument is just ``TRUE`` (default), temporary file will be used and will be
deleted once response object is destroyed. Setting argument to ``FALSE`` disables the streaming functionality.

When using streaming, ``send()`` method will return object of class ``Zend\Http\Response\Stream``, which
has two useful methods: ``getStreamName()`` will return the name of the file where the response is stored, and
``getStream()`` will return stream from which the response could be read.

You can either write the response to pre-defined file, or use temporary file for storing it and send it out or
write it to another file using regular stream functions.



      .. _zend.http.client.streaming.example-2:

      .. rubric:: Receiving file from HTTP server with streaming

      .. code-block:: php
         :linenos:

         $client->setStream(); // will use temp file
         $response = $client->send();
         // copy file
         copy($response->getStreamName(), "my/downloads/file");
         // use stream
         $fp = fopen("my/downloads/file2", "w");
         stream_copy_to_stream($response->getStream(), $fp);
         // Also can write to known file
         $client->setStream("my/downloads/myfile")->send();