repo_zf1/documentation/manual/en/module_specs/Zend_Http_Client.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.http.client">
    <title>Introduction</title>

    <para>
        <classname>Zend_Http_Client</classname> provides an easy interface for preforming Hyper-Text
        Transfer Protocol (HTTP) requests. <classname>Zend_Http_Client</classname> supports most
        simple features expected from an <acronym>HTTP</acronym> client, as well as some more
        complex features such as <acronym>HTTP</acronym> authentication and file uploads. Successful
        requests (and most unsuccessful ones too) return a <classname>Zend_Http_Response</classname>
        object, which provides access to the response's headers and body (see
        <xref linkend="zend.http.response" />).
    </para>

    <sect2 id="zend.http.client.usage">
        <title>Using Zend_Http_Client</title>

        <para>
            The class constructor optionally accepts a URL as its first parameter
            (can be either a string or a <classname>Zend_Uri_Http</classname> object), and an array
            or <classname>Zend_Config</classname> object containing configuration options. Both can
            be left out, and set later using the setUri() and setConfig() methods.

            <example id="zend.http.client.introduction.example-1">
                <title>Instantiating a Zend_Http_Client Object</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org', array(
    'maxredirects' => 0,
    'timeout'      => 30));

// This is actually exactly the same:
$client = new Zend_Http_Client();
$client->setUri('http://example.org');
$client->setConfig(array(
    'maxredirects' => 0,
    'timeout'      => 30));

// You can also use a Zend_Config object to set the client's configuration
$config = new Zend_Config_Ini('httpclient.ini, 'secure');
$client->setConfig($config);
]]></programlisting>
            </example>

            <note>
                <para>
                    <classname>Zend_Http_Client</classname> uses
                    <classname>Zend_Uri_Http</classname> to validate URLs. This means
                    that some special characters like the pipe symbol ('|') or the
                    caret symbol ('^') will not be accepted in the URL by default.
                    This can be modified by setting the 'allow_unwise' option of
                    <classname>Zend_Uri</classname> to '<constant>TRUE</constant>'. See <xref
                        linkend="zend.uri.validation.allowunwise" /> for more information.
                </para>
            </note>
        </para>
    </sect2>

    <sect2 id="zend.http.client.configuration">
        <title>Configuration Parameters</title>

        <para>
            The constructor and setConfig() method accept an associative array
            of configuration parameters, or a <classname>Zend_Config</classname> object. Setting
            these parameters is optional, as they all have default values.

            <table id="zend.http.client.configuration.table">
                <title>Zend_Http_Client configuration parameters</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Parameter</entry>
                            <entry>Description</entry>
                            <entry>Expected Values</entry>
                            <entry>Default Value</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>maxredirects</entry>
                            <entry>Maximum number of redirections to follow (0 = none)</entry>
                            <entry>integer</entry>
                            <entry>5</entry>
                        </row>

                        <row>
                            <entry>strict</entry>

                            <entry>
                                Whether perform validation on header names. When set to
                                <constant>FALSE</constant>, validation functions will be skipped.
                                Usually this should not be changed
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>

                        <row>
                            <entry>strictredirects</entry>

                            <entry>
                                Whether to strictly follow the <acronym>RFC</acronym> when
                                redirecting (see <xref linkend="zend.http.client.redirections" />)
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>useragent</entry>
                            <entry>User agent identifier string (sent in request headers)</entry>
                            <entry>string</entry>
                            <entry>'Zend_Http_Client'</entry>
                        </row>

                        <row>
                            <entry>timeout</entry>
                            <entry>Connection timeout (seconds)</entry>
                            <entry>integer</entry>
                            <entry>10</entry>
                        </row>

                        <row>
                            <entry>httpversion</entry>
                            <entry>HTTP protocol version (usually '1.1' or '1.0')</entry>
                            <entry>string</entry>
                            <entry>'1.1'</entry>
                        </row>

                        <row>
                            <entry>adapter</entry>

                            <entry>
                                Connection adapter class to use (see <xref
                                    linkend="zend.http.client.adapters" />)
                            </entry>

                            <entry>mixed</entry>
                            <entry>'Zend_Http_Client_Adapter_Socket'</entry>
                        </row>

                        <row>
                            <entry>keepalive</entry>

                            <entry>
                                Whether to enable keep-alive connections with the server. Useful and
                                might improve performance if several consecutive requests to the
                                same server are performed.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>storeresponse</entry>

                            <entry>
                                Whether to store last response for later retrieval with
                                <methodname>getLastResponse()</methodname>. If set to
                                <constant>FALSE</constant>
                                <methodname>getLastResponse()</methodname> will return
                                <constant>NULL</constant>.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>
                        <row>
                            <entry>encodecookies</entry>

                            <entry>
                                Whether to pass the cookie value through urlencode/urldecode.
                                Enabling this breaks support with some web servers.
                                Disabling this limits the range of values the cookies can contain.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>
    </sect2>

    <sect2 id="zend.http.client.basic-requests">
        <title>Performing Basic HTTP Requests</title>

        <para>
            Performing simple <acronym>HTTP</acronym> requests is very easily done using the
            request() method, and rarely needs more than three lines of code:

            <example id="zend.http.client.basic-requests.example-1">
                <title>Performing a Simple GET Request</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org');
$response = $client->request();
]]></programlisting>
            </example>

            The request() method takes one optional parameter - the request method.
            This can be either GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS or
            CONNECT as defined by the <acronym>HTTP</acronym> protocol

            <footnote>
              <para>
                See RFC 2616 - <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html" />.
              </para>
            </footnote>.

            For convenience, these are all defined as class constants:
            Zend_Http_Client::GET, Zend_Http_Client::POST and so on.
        </para>

        <para>
            If no method is specified, the method set by the last setMethod()
            call is used. If setMethod() was never called, the default request
            method is GET (see the above example).

            <example id="zend.http.client.basic-requests.example-2">
                <title>Using Request Methods Other Than GET</title>

                <programlisting language="php"><![CDATA[
// Preforming a POST request
$response = $client->request('POST');

// Yet another way of preforming a POST request
$client->setMethod(Zend_Http_Client::POST);
$response = $client->request();
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.client.parameters">
        <title>Adding GET and POST parameters </title>

        <para>
            Adding GET parameters to an <acronym>HTTP</acronym> request is quite simple, and can
            be done either by specifying them as part of the URL, or by using
            the setParameterGet() method.
            This method takes the GET parameter's name as its first parameter,
            and the GET parameter's value as its second parameter.
            For convenience, the setParameterGet() method can also accept a
            single associative array of name => value GET variables - which may
            be more comfortable when several GET parameters need to be set.

            <example id="zend.http.client.parameters.example-1">
                <title>Setting GET Parameters</title>

                <programlisting language="php"><![CDATA[
// Setting a get parameter using the setParameterGet method
$client->setParameterGet('knight', 'lancelot');

// This is equivalent to setting such URL:
$client->setUri('http://example.com/index.php?knight=lancelot');

// Adding several parameters with one call
$client->setParameterGet(array(
    'first_name'  => 'Bender',
    'middle_name' => 'Bending'
    'made_in'     => 'Mexico',
));
]]></programlisting>
            </example>
        </para>

        <para>
            While GET parameters can be sent with every request method, POST
            parameters are only sent in the body of POST requests. Adding POST
            parameters to a request is very similar to adding GET parameters,
            and can be done with the setParameterPost() method, which is
            similar to the setParameterGet() method in structure.

            <example id="zend.http.client.parameters.example-2">
                <title>Setting POST Parameters</title>

                <programlisting language="php"><![CDATA[
// Setting a POST parameter
$client->setParameterPost('language', 'fr');

// Setting several POST parameters, one of them with several values
$client->setParameterPost(array(
    'language'  => 'es',
    'country'   => 'ar',
    'selection' => array(45, 32, 80)
));
]]></programlisting>
            </example>

            Note that when sending POST requests, you can set both GET and
            POST parameters. On the other hand, while setting POST parameters
            for a non-POST request will not trigger and error, it is useless.
            Unless the request is a POST request, POST parameters are simply
            ignored.
        </para>
    </sect2>

    <sect2 id="zend.http.client.accessing_last">
        <title>Accessing Last Request and Response</title>

        <para>
            <classname>Zend_Http_Client</classname> provides methods of accessing the last request
            sent and last response received by the client object.
            <classname>Zend_Http_Client->getLastRequest()</classname> takes no parameters
            and returns the last <acronym>HTTP</acronym> request sent by the client as a string.
            Similarly, <classname>Zend_Http_Client->getLastResponse()</classname> returns
            the last <acronym>HTTP</acronym> response received by the client as a
            <link linkend="zend.http.response">Zend_Http_Response</link> object.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->