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
        <link linkend="zend.http.response">this section</link>).
    </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 <link
                        linkend="zend.uri.validation.allowunwise">this section</link> 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 <link
                                    linkend="zend.http.client.redirections">this section</link>)
                            </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 <link
                                    linkend="zend.http.client.adapters">this section</link>)
                            </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 <property>GET</property>, <property>POST</property>,
            <property>PUT</property>, <property>HEAD</property>, <property>DELETE</property>,
            <property>TRACE</property>, <property>OPTIONS</property> or <property>CONNECT</property>
            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
            <methodname>setMethod()</methodname> call is used. If
            <methodname>setMethod()</methodname> was never called, the default request
            method is <constant>GET</constant> (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 <constant>GET</constant> 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 <constant>GET</constant> parameter's name as its first parameter,
            and the <constant>GET</constant> parameter's value as its second parameter.
            For convenience, the setParameterGet() method can also accept a
            single associative array of name => value <constant>GET</constant> variables - which may
            be more comfortable when several <constant>GET</constant> 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 <constant>GET</constant> 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 <constant>GET</constant> 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 <constant>GET</constant> 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:
-->