11.3. Zend_Http_Client - Connection Adapters

11.3.1. Overview

Zend_Http_Client is based on a connection adapter design. The connection adapter is the object in charge of performing the actual connection to the server, as well as writing requests and writing responses. This connection adapter can be replaced, and you can create and extend the default connection adapters to suite your special needs, without the need to extend or replace the entire HTTP client class, and with the same interface.

Currently, the Zend_Http_Client class provides three built-in connection adapters:

  • Zend_Http_Client_Adapter_Socket (default)

  • Zend_Http_Client_Adapter_Proxy

  • Zend_Http_Client_Adapter_Test

The Zend_Http_Client object's adapter connection adapter is set using the 'adapter' configuration option. When instantiating the client object, you can set the 'adapter' configuration option to a string containing the adapter's name (eg. 'Zend_Http_Client_Adapter_Socket') or to a variable holding an adapter object (eg new Zend_Http_Client_Adapter_test). You can also set the adapter later, using the Zend_Http_Client->setConfig() method.

11.3.2. The Socket Adapter

The default connection adapter is the Zend_Http_Client_Adapter_Socket adapter - this adapter will be used unless you explicitly set the connection adapter. The Socket adapter is based on PHP's built-in fsockopen() function, and does not require any special extensions or compilation flags.

The Socket adapter allows one extra configuration option (passed to the Zend_Http_Client->setConfig() or to the constructor): 'ssltransport'. This parameter, if set, is expected to be a string and defaults to 'sslv2'. Changing this will override the stream transport layer used for HTTPS connections. Possible values are 'ssl', 'sslv2', 'sslv3' and 'tls'. Generally speaking, any other stream transport layer supported by your PHP installation can also be used - but the results might be unexpected, so you should only use such values if you know exactly what you are doing. [2].

Пример 11.15. Changing the HTTPS transport layer

<?php
    // Set the configuration parameters
    $config = array(
        'adapter'      => 'Zend_Http_Client_Adapter_Socket',
        'ssltransport' => 'tls'
    );
    
    // Instantiate a client object
    $client = Zend_Http_Client('https://www.example.com', $config);
    
    // The following request will be sent over a TLS secure connection.
    $response = $client->request();
?>

The result of the example above will be similar to opening a TCP connection using the following PHP command:

fsockopen('tls://www.example.com', 443)

11.3.3. The Proxy Adapter

The Zend_Http_Client_Adapter_Proxy adapter is similar to the default Socket adapter - only the connection is made through an HTTP proxy server instead of a direct connection to the target server. This allows usage of Zend_Http_Client behind proxy servers - which is sometimes needed for security or performance reasons.

Using the Proxy adapter requires several additional configuration parameters to be set, in addition to the default 'adapter' option:

Таблица 11.2. Zend_Http_Client configuration parameters

Parameter Description Expected Type Example Value
proxy_host Proxy server address string 'proxy.myhost.com' or '10.1.2.3'
proxy_port Proxy server TCP port integer 8080 (default) or 81
proxy_user Proxy user name, if required string 'shahar' or '' for none (default)
proxy_pass Proxy password, if required string 'secret' or '' for none (default)
proxy_auth Proxy HTTP authentication type string Zend_Http_Client::AUTH_BASIC (default)

proxy_host should always be set - if it is not set, the client will fall back to a direct connection using Zend_Http_Client_Adapter_Socket. proxy_port defaults to '8080' - if your proxy listens on a different port you must set this one as well.

proxy_user and proxy_pass are only required if your proxy server requires you to authenticate. Providing these will add a 'Proxy-Authentication' header to the request. If your proxy does not require authentication, you can leave these two options out.

proxy_auth sets the proxy authentication type, if your proxy server requires authentication. Possibly values are similar to the ones accepted by the Zend_Http_Client::setAuth() method. Currently, only basic authentication (Zend_Http_Client::AUTH_BASIC) is supported.

Пример 11.16. Using Zend_Http_Client behind a proxy server

<?php
    // Set the configuration parameters
    $config = array(
        'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
        'proxy_host' => 'proxy.int.zend.com',
        'proxy_port' => 8000,
        'proxy_user' => 'shahar.e',
        'proxy_pass' => 'bananashaped'
    );
    
    // Instantiate a client object
    $client = Zend_Http_Client('http://www.example.com', $config);
    
    // Continue working...
?>

As mentioned, if proxy_host is not set or is set to a blank string, the connection will fall back to a regular direct connection. This allows you to easily write your application in a way that allows a proxy to be used optionally, according to a configuration parameter.

11.3.4. The Test Adapter

Sometimes, it is very hard to test code that relies on HTTP connections. For example, testing an application that pulls an RSS feed from a remote server will require a network connection, which is not always available.

For this reason, the Zend_Http_Client_Adapter_Test adapter is provided. You can write your application to use Zend_Http_Client, and just for testing purposes, for example in your unit testing suite, you can replace the default adapter with a Test adapter, allowing you to run tests without actually performing server connections.

The Zend_Http_Client_Adapter_Test adapter provides an additional method, setResponse() method. This method takes one parameter, which represents an HTTP response as either text or a Zend_Http_Response object. Once set, your Test adapter will always return this response, without even performing an actual HTTP request.

Пример 11.17. Testing Your Code Without Accessing The Network

<?php
    // Instantiate a new adapter and client
    $adapter = new Zend_Http_Client_Adapter_Test();
    $client = Zend_Http_Client('http://www.example.com', array(
        'adapter' => $adapter
    ));
    
    // Set the expected response
    $adapter->setResponse(
        "HTTP/1.1 200 OK"        . "\r\n" .
        "Content-type: text/xml" . "\r\n" .
                                   "\r\n" . 
        '<?xml version="1.0" encoding="UTF-8"?>' . 
        '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"' . 
	    '     xmlns:wfw="http://wellformedweb.org/CommentAPI/"' . 
	    '     xmlns:dc="http://purl.org/dc/elements/1.1/">' . 
        '  <channel>' . 
        '    <title>Premature Optimization</title>' . 
        // and so on...
        '</rss>');
    
    $response = $client->request('GET');
    // .. continue parsing $response..
?>

The above example shows how you can preset your HTTP client to return the response you need. Then, you can continue testing your own code, without being dependent on a network connection, the server's response, etc. In this case, the test would continue to check how the application parses the XML in the response body.

11.3.5. Creating your own connection adapters

You can create your own connection adapters and use them. You could, for example, create a connection adapter that uses persistent sockets, or a connection adapter with caching abilities, and use them as needed in your application.

In order to do so, you must create your own adapter class that implements the Zend_Http_Client_Adapter_Interface interface. The following example shows the skeleton of a user-implemented adapter class. All the public functions defined in this example must be defined in your adapter as well:

Пример 11.18. Creating your own connection adapter

<?php
class MyApp_Http_Client_Adapter_BananaProtocol implements Zend_Http_Client_Adapter_Interface
{    
    /**
     * Set the configuration array for the adapter
     *
     * @param array $config
     */
    public function setConfig($config = array())
    {
        // This rarely changes - you should usually copy the implementation
        // in Zend_Http_Client_Adapter_Socket.
    }
    
    /**
     * Connect to the remote server
     *
     * @param string  $host
     * @param int     $port
     * @param boolean $secure
     */
    public function connect($host, $port = 80, $secure = false)
    {
        // Set up the connection to the remote server
    }
    
    /**
     * Send request to the remote server
     *
     * @param string        $method
     * @param Zend_Uri_Http $url
     * @param string        $http_ver
     * @param array         $headers
     * @param string        $body
     * @return string Request as text
     */
    public function write($method, $url, $http_ver = '1.1', $headers = array(), $body = '')
    {
        // Send request to the remote server.
        // This function is expected to return the full request (headers and body) as a string
    }
    
    /**
     * Read response from server
     *
     * @return string
     */
    public function read()
    {
        // Read response from remote server and return it as a string
    }
    
    /**
     * Close the connection to the server
     *
     */
    public function close()
    {
        // Close the connection to the remote server - called last.
    }
}    

// Then, you could use this adapter:
$client = new Zend_Http_Client(array(
    'adapter' => 'MyApp_Http_Client_Adapter_BananaProtocol'
));


[2] See Appendix O in the PHP manual for a list of supported socket transports: http://www.php.net/manual/en/transports.php