Latest Project Plan
Zend_Http_Client

Why is this here?

Zend_Http_Client already exists and is being used by other components of the Framework. Additionally, a rewritten Zend_Http_Client which is fully functional already exists in the incubator. So why is this proposal here?

Simple: It became clear that the best way to frame up the development of the new Zend_Http_Client would be to create some kind of spec for it, which was never done. It seemes that the best way to do this is by writting an actual proposal for it - just like you would for a new component in the Framework.

Zend Framework: Zend_Http_Client Component Proposal

Proposed Component Name	Zend_Http_Client
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Http_Client
Proposers	shahar.e@zend.com stefan.koopmanschap@gmail.com
Revision	0.1 - 9 October 2006: Initial proposal 0.2 - 18 October 2006: Added some code skeletons (wiki revision: 16)

This component will be able to send HTTP requests using all methods, over secure and non-secure connections
This component will be adapter based: Can use either a sockets based adapter or cURL based adapter to perform the request
This component will be extremely simple when perfoming common requests: Simple GET and POST requests can be performed with 2 - 3 lines of code.
This component will provide easy interface to the less common HTTP tasks such as file uploads, sending RAW HTTP data, etc.
This component will strictly adhere to the standards when generating requests, but will be flexible and take de-facto "standards" in account when parsing server responses
This component will allow performing several requests with one object.
This component will automatically provide cookie stickeyness when performing consecutive requests to the same domain
This component will be serializable and cacheable
This component will be subclassable, to allow special clients to be based on it (eg: cache-enabled, HTTP client, special authentication service aware HTTP client, etc.)

Specific HTTP features:

Adding HTTP POST and GET parameters
HTTP POST data can be sent using both application/x-form-urlencoded and multipart/form-data content types
Setting arbitrary HTTP headers
Adding HTTP cookies
Cookie stickeyness: automatically resend cookies set by the server on consecutive requests (if set to)
File uploads using the HTTP POST method
Sending raw POST data and manually setting the body content-type
Automatically handle redirections (up to a specified limit)
Support HTTP authentication

4. Dependencies on Other Framework Components

Zend_Exception
Zend_Uri_Http

5. Theory of Operation

A Zend_Http_Client is instanciated using a dynamic constructor, provided two optional parameters: A target URI and an array of parameters. The parameters set the more "static" variables, such as the adapter, the connection timeout, redirection limit, user-agent string and more. Once instanciated, an object can recieve parameters, headers, cookies etc. as needed. Then, the request is sent (using one method which accepts the request method as a parameter) - and a Zend_Http_Response object is returned.

If the response contains cookies - those will be kept for consecutive requests. If the response is a redirection, it will be followed, until a final response is recieved and returned to the user.

The Zend_Http_Response class is mostly a container object for an HTTP response message, providing easy access to response parameters such as status code (200, 404), headers and body. On the other hand, Zend_Http_Response is also responsible for parsing an HTTP response message, and provides several static methods to help doing so - including methods to decode encoded or compressed responses.

Zend_Http_Cookie is a container class for a single cookie, also providing methods to test whether a cookie matches a request scenario (URL, time). Zend_Http_Cookiejar is a special class that facilitates the storage and retrevial of a set of cookies. This class is used by the Zend_Http_Client to facilitate cookie stickeyness - allowing the client to automatically resend cookies received in past requests. This object can be cached or stored in $_SESSION, to implement cookie (or session) stickeyness across requests.

6. Milestones / Tasks

Also see the latest project plan and design notes: Zend_Http_Client.
Since Zend_Http_Client is already in the incubator for some time, and is mostly working, these are the proposed milestones for it's completion:

Milestone 1: Set up the parameters array and remove methods that set "static" parameters (setTimeOut(), etc.)
Milestone 2: Set up the adapter interface and move to an adapter-based design
Milestone 3: Unit tests cover most of the code
Milestone 4: Documentation covers most of the code
Mulestone 5: Code moved out of the incubator

7. Class Index

Zend_Http_Client
Zend_Http_Client_Adapter_Interface
Zend_Http_Client_Adapter_Socket
Zend_Http_Client_Adapter_Psocket
Zend_Http_Client_Adapter_Curl
Zend_Http_Client_Exception
Zend_Http_Response
Zend_Http_Cookie
Zend_Http_Cookiejar

8. Use Cases

UC-01

// Sending a simple GET request
$client = new Zend_Http_Client('http://www.example.com');
$response = $client->request();

UC-02

// Sending a GET request with parameters
$client = new Zend_Http_Client('http://www.example.com');
$client->setParameterGet('foo', 'bar');
$response = $client->request();

UC-03

// Sending a POST request with some GET and POST parameters over HTTPS with authentication
$client = new Zend_Http_Client('https://www.example.com');
$client->setParameterGet('swallow', 'african');
$client->setParameterPost('shape', 'banana');
$client->setAuth('shahar', '123456', Zend_Http_Client::AUTH_BASIC);
$response = $client->request(Zend_Http_Client::POST);

UC-04

// Uploading arbitrary data as a file
$xml = '<someXml><element><child1>foo</child1><child2>bar</child2></element></someXml>';
$client = new Zend_Http_Client('http://www.example.com');
$client->setFileUpload('file.xml', 'xmlfile', $xml, 'text/xml');
$response = $client->request('POST');

// Uploading an existing file 
$client->resetParameters();
$client->setFileUpload('/tmp/somefile', 'somefile');
$response = $client->request('POST');

// Sending raw POST data
$client->resetParameters();
$client->setRawData('bla bla bla', 'text/plain');
$response = $client->request('POST');

UC-05

// Performing consecutive requests, preserving session cookies in $_SESSION
$client = new Zend_Http_Client();
if (isset($_SESSION['cookieJar'])) {
	// Try to load cookie jar from $_SESSION
	$client->setCookiejar($_SESSION['cookieJar']);
} else {
	// No cookie jar - access login page and save cookies
	$client->setCookiejar();
	$client->setConfig(array('maxredirects' => 0);
	$client->setUri('http://www.example.com/login');
	$client->setParameterPost('user', 'shahar');
	$client->setParameterPost('pass', '123456');
	$client->request('POST');
	$client->setConfig(array('maxredirects' => 5);
	$client->resetParameters();
}

// preform actual request
$client->setUri('http://www.example.com');
$response = $client->request();

// Save cookie jar to $_SESSION
$_SESSION['cookieJar'] = $client->getCookiejar();

9. Class Skeletons

<?php

class Zend_Http_Client
{
    /**
     * HTTP request methods 
     */
    const GET     = 'GET';
    const POST    = 'POST';
    const PUT     = 'PUT';
    const HEAD    = 'HEAD';
    const DELETE  = 'DELETE';
    const TRACE   = 'TRACE';
    const OPTIONS = 'OPTIONS';
    const CONNECT = 'CONNECT';
	
    /**
     * Supported HTTP Authentication methods
     */
    const AUTH_BASIC = 'basic';
    const AUTH_DIGEST = 'digest';

    /**
     * HTTP protocol versions
     */
    const HTTP_1 = 1.1;
    const HTTP_0 = 1.0;
    
    /**
     * POST data encoding methods
     */
    const ENC_URLENCODED = 'application/x-www-form-urlencoded';
    const ENC_FORMDATA   = 'multipart/form-data';
    
    /**
     * Configuration array, set using the constructor or using ::setConfig()
     *
     * @var unknown_type
     */
    protected $config = array(
    	'maxredirects'		=> 5,
    	'strictredirects'	=> false,
    	'useragent'		=> 'Zend_Http_Client/0.1.5',
    	'timeout'		=> 10,
    	'adapter'		=> 'Zend_Http_Client_Adapter_Socket',
    	'httpversion'		=> self::HTTP_1 
    );

    /**
     * The adapter used to preform the actual connection to the server
     *
     * @var Zend_Http_Client_Adapter_Interface
     */
    protected $adapter;
    
    /**
     * Request URI
     *
     * @var Zend_Uri_Http
     */
    protected $uri;
    
    /**
     * Associative array of request headers 
     *
     * @var array
     */
    protected $headers = array();

    /**
     * HTTP request method
     *
     * @var string
     */
    protected $method = self::GET;
    
    /**
     * Associative array of GET parameters
     *
     * @var array
     */
    protected $paramsGet = array();
    
    /**
     * Assiciative array of POST parameters
     *
     * @var array
     */
    protected $paramsPost = array();
    
    /**
     * Request body content type (for POST requests)
     *
     * @var string
     */
    protected $enctype = null;
    
    /**
     * The raw post data to send. Could be set by setRawPostData($data, $enctype).
     *
     * @var string
     */
    protected $raw_post_data = null;
    
    /**
     * HTTP Authentication settings
     *
     * Expected to be an associative array with this structure:
     * $this->auth = array('user' => 'username', 'password' => 'password', 'type' => 'basic')
     * Where 'type' should be one of the supported authentication types (see the AUTH_* 
     * constants), for example 'basic' or 'digest'.
     * 
     * If null, no authentication will be used.
     * 
     * @var array|null
     */
    protected $auth;

    /**
     * File upload arrays (used in POST requests)
     * 
     * An associative array, where each element is of the format:
     *   'name' => array('filename.txt', 'text/plain', 'This is the actual file contents')
     *
     * @var array
     */
    protected $files = array();
    
    /**
     * The client's cookie jar
     *
     * @var Zend_Http_Cookiejar
     */
    protected $cookiejar = null;

    /**
     * The last HTTP request sent by the client, as string
     *
     * @var string
     */
    protected $last_request = null;

    /**
     * Redirection counter
     *
     * @var int
     */
    protected $redirectCounter = 0;

    /**
     * Contructor method. Will create a new HTTP client. Accepts the target
     * URL and optionally and array of headers.
     *
     * @param Zend_Uri_Http|string $uri
     * @param array $headers Optional request headers to set
     */
    public function __construct($uri = null, $config = null);
        
    /**
     * Set the URI for the next request
     *
     * @param Zend_Uri_Http|string $uri
     * @return Zend_Http_Client
     */
    public function setUri($uri);
    
    /**
     * Get the URI for the next request
     *
     * @param boolean $as_string If true, will return the URI as a string
     * @return Zend_Uri_Http|string
     */
    public function getUri($as_string = false);

    /**
     * Set configuration parameters for this HTTP client
     *
     * @param array $config
     * @return Zend_Http_Client
     */
    public function setConfig($config = array());
    
    /**
     * Set the next request's method
     * 
     * Validated the passed method and sets it. If we have files set for 
     * POST requests, and the new method is not POST, the files are silently
     * dropped. 
     *
     * @param string $method
     * @return Zend_Http_Client
     */
    public function setMethod($method = self::GET);
    
    /**
     * Set one or more request headers
     * 
     * This function can be used in several ways to set the client's request
     * headers:
     * 1. By providing two parameters: $name as the header to set (eg. 'Host')
     *    and $value as it's value (eg. 'www.example.com').
     * 2. By providing a single header string as the only parameter
     *    eg. 'Host: www.example.com'
     * 3. By providing an array of headers as the first parameter
     *    eg. array('host' => 'www.example.com', 'x-foo: bar'). In This case 
     *    the function will call itself recursively for each array item.
     * 
     * In all cases, the third parameter $override decides whether to overwrite
     * the value of this header if it's already set (default), or to add another
     * header with the same name to the list of headers (good for repeating
     * headers like 'Cookie').
     * 
     * @param string|array $name Header name, full header string ('Header: value')
     *     or an array of headers
     * @param mixed $value Header value or null
     * @param boolean $override Whether to override header if it already exists
     * @return Zend_Http_Client
     */
    public function setHeaders($name, $value = null, $override = true);
    
    /**
     * Get the value of a specific header
     *
     * Note that if the header has more than one value, an array
     * will be returned. 
     * 
     * @param unknown_type $key
     * @return string|array|null The header value or null if it is not set
     */
    public function getHeader($key);
    
    /**
     * Set a GET parameter for the request. Wrapper around _setParameter
     *
     * @param string $name
     * @param string $value
     * @param boolean $override Whether to overwrite the parameter's value
     * @return Zend_Http_Client
     */    
    public function setParameterGet($name, $value, $override = true);
    
    /**
     * Set a POST parameter for the request. Wrapper around _setParameter
     *
     * @param string $name
     * @param string $value
     * @param boolean $override Whether to overwrite the parameter's value
     * @return Zend_Http_Client
     */        
    public function setParameterPost($name, $value, $override = true);
    
    /**
     * Set a GET or POST parameter - used by SetParameterGet and SetParameterPost
     *
     * @param string $type GET or POST
     * @param string $name
     * @param string $value
     * @param boolean $override Whether to replace old value, or add it as an array of values
     */
    protected function _setParameter($type, $name, $value, $override = true);

    /**
     * Set HTTP authentication parameters
     * 
     * $type should be one of the supported types - see the self::AUTH_* 
     * constants.
     *  
     * To enable authentication: 
     *     @example $this->setAuth('shahar', 'secret', Zend_Http_Client::AUTH_BASIC);
     * To disable authentication: 
     *     @example $this->setAuth(false);
     *
     * @see http://www.faqs.org/rfcs/rfc2617.html
     * @param string|false $user User name or false disable authentication
     * @param string $password Password
     * @param string $type Authentication type
     * @return Zend_Http_Client
     */
    public function setAuth($user, $password = '', $type = self::AUTH_BASIC);

    /**
     * Set the HTTP client's cookie jar.
     * 
     * A cookie jar is an object that holds and maintains cookies across HTTP requests
     * and responses.
     *
     * @param Zend_Http_Cookiejar|boolean $cookiejar Exisitng cookiejar object, true to create a new one, false to disable
     * @return Zend_Http_Client
     */
    public function setCookiejar($cookiejar = true);
    
    /**
     * Return the current cookie jar or null if none.
     *
     * @return Zend_Http_Cookiejar|null
     */
    public function getCookiejar();
    
    /**
     * Add a cookie to the request. If the client has no Cookie Jar, the cookies 
     * will be added directly to the headers array as "Cookie" headers.
     *
     * @param Zend_Http_Cookie|string $cookie
     * @param string|null $value If "cookie" is a string, this is the cookie value. 
     * @return Zend_Http_Client
     */
    public function setCookie($cookie, $value = null);
    
    /**
     * Set a file to upload (using a POST request)
     *
     * Can be used in two ways:
     *
     * 1. $data is null (default): $filename is treated as the name if a local file which
     *    will be read and sent. Will try to guess the content type using mime_content_type().
     * 2. $data is set - $filename is sent as the file name, but $data is sent as the file
     *    contents and no file is read from the file system. In this case, you need to 
     *    manually set the content-type ($ctype) or it will default to 
     *    application/octet-stream.
     * 
     * @param string $filename Name of file to upload, or name to save as
     * @param string $formname Name of form element to send as
     * @param string $data Data to send (if null, $filename is read and sent)
     * @param string $ctype Content type to use (if $data is set and $ctype is 
     *     null, will be application/octet-stream)
     * @return Zend_Http_Client
     */
    public function setFileUpload($filename, $formname, $data = null, $ctype = null);
    
    /**
     * Set the encoding type for POST data
     *
     * @param string $enctype
     * @return Zend_Http_Client
     */
    public function setEncType($enctype = self::ENC_URLENCODED);
    
    /**
     * Set the raw (already encoded) POST data. 
     *
     * This function is here for two reasons: 
     * 1. For advanced user who would like to set their own data, already encoded
     * 2. For backwards compatibilty: If someone uses the old post($data) method.
     *    this method will be used to set the encoded data. 
     *
     * @param string $data
     * @param string $enctype
     * @return Zend_Http_Client
     */
    public function setRawData($data, $enctype = null);
    
    /**
     * Clear all GET and POST parameters
     * 
     * Should be used to reset the request parameters if the client is 
     * used for several concurrent requests.
     * 
     * @return Zend_Http_Client
     */
    public function resetParameters();
    
    /**
     * Prepare the request headers
     * 
     * @return array
     */
    protected function prepare_headers();
    
    /**
     * Prepare the request body (for POST and PUT requests)
     * 
     * @return string
     */
    protected function prepare_body();

    /**
     * Send the HTTP request and return an HTTP response object
     *
     * @param string $method
     * @return Zend_Http_Response
     */
    public function request($method = null);

    /**
     * Get the last HTTP request as string
     * 
     * @return string
     */
    public function getLastRequest();

    /**
     * Get the number of redirections done on the last request
     *
     * @return int
     */
    public function getRedirectionsCount();
    
    /**
     * Helper method that gets a possibly multi-level parameters array (get or
     * post) and flattens it.
     * 
     * The method returns an array of (key, value) pairs (because keys are not
     * necessarily unique. If one of the parameters in as array, it will also 
     * add a [Zend_Db_Adapter_Odbtp_Mssql] suffix to the key.
     *
     * @param array $parray The parameters array
     * @param bool $urlencode Whether to urlencode the name and value
     * @return array
     */
    protected function _getParametersRecursive($parray, $urlencode = false);

    /**
     * Encode data to a multipart/form-data part suitable for a POST request.
     *
     * @param string $boundary
     * @param string $name
     * @param mixed $value
     * @param string $filename
     * @param array $headers Associative array of optional headers @example ("Content-transfer-encoding" => "binary")
     * @return string
     */
    static public function encodeFormData($boundary, $name, $value, $filename = null, $headers = array());
    
    /**
     * Create a HTTP authentication "Authorization:" header according to the 
     * specified user, password and authentication method.
     *
     * @see http://www.faqs.org/rfcs/rfc2617.html
     * @param string $user
     * @param string $password
     * @param string $type
     * @return string
     */
    static public function encodeAuthHeader($user, $password, $type = self::AUTH_BASIC);
}

<?php

interface Zend_Http_Client_Adapter_Interface 
{	
	/**
	 * Set the configuration array for the adapter
	 *
	 * @param array $config
	 */
	public function setConfig($config = array());
	
	/**
	 * Connect to the remote server
	 *
	 * @param string  $host
	 * @param int     $port
	 * @param boolean $secure
	 */
	public function connect($host, $port = 80, $secure = false);
	
	/**
	 * Send request to the remote server
	 *
	 * @param string $method
	 * @param Zend_Uri_Http $url
	 * @param float $http_ver
	 * @param array  $headers
	 * @param string $body
	 */
	public function write($method, $url, $http_ver = 1.1, $headers = array(), $body = '');
	
	/**
	 * Read response from server
	 *
	 * @return string
	 */
	public function read();
	
	/**
	 * Close the connection to the server
	 *
	 */
	public function close();
}

<?php

class Zend_Http_Response
{
    /**
     * The HTTP version (1.0, 1.1)
     *
     * @var string
     */
    protected $version;

    /**
     * The HTTP response code
     *
     * @var int
     */
    protected $code;

    /**
     * The HTTP response code as string 
     * (e.g. 'Not Found' for 404 or 'Internal Server Error' for 500)
     *
     * @var string
     */
    protected $message;

    /**
     * The HTTP response headers array
     *
     * @var array
     */
    protected $headers = array();

    /**
     * The HTTP response body
     *
     * @var string
     */
    protected $body;

    /**
     * HTTP response constructor
     * 
     * In most cases, you would use Zend_Http_Response::factory to parse an 
     * HTTP response string and create a new Zend_Http_Response object.
     * 
     * NOTE: The constructor no longer accepts nulls or empty values for the 
     * code and headers and will throw an exception if the passed values do not
     * form a valid HTTP responses. 
     * 
     * If no message is passed, the message will be guessed according to the 
     * response code.
     *
     * @param int $code Response code (200, 404, ...)
     * @param array $headers Headers array
     * @param string $body Response body
     * @param string $version HTTP version
     * @param string $message Response code as text
     * @throws Zend_Http_Exception
     */
    public function __construct($code, $headers, $body = null, $version = '1.1', $message = null);

    /**
     * Check whether the response is an error
     *
     * @return boolean
     */
    public function isError();

    /**
     * Check whether the response in successful
     * 
     * @return boolean
     */
    public function isSuccessful();

    /**
     * Check whether the response is a redirection
     * 
     * @return boolean
     */
    public function isRedirect();

    /**
     * Get the response body as string
     * 
     * This method returns the body of the HTTP response (the content), as it 
     * should be in it's readable version - that is, after decoding it (if it
     * was decoded), deflating it (if it was gzip compressed), etc.
     * 
     * If you want to get the raw body (as transfered on wire) use 
     * $this->getRawBody() instead.
     * 
     * @return string
     */
    public function getBody();

    /**
     * Get the raw response body (as transfered "on wire") as string
     * 
     * If the body is encoded (with Transfer-Encoding, not content-encoding -
     * IE "chunked" body), gzip compressed, etc. it will not be decoded. 
     * 
     * @return string
     */
    public function getRawBody();

    /**
     * Get the HTTP version of the response
     *
     * @return string
     */
    public function getVersion();

    /**
     * Get the HTTP response status code
     *
     * @return int
     */
    public function getStatus();

    /**
     * Return a message describing the HTTP response code 
     * (Eg. "OK", "Not Found", "Moved Permanently")
     *
     * @return string
     */
    public function getMessage();

    /**
     * Get the response headers
     *
     * @return array
     */
    public function getHeaders();

    /**
     * Get a specific header as string, or null if it is not set
     *
     * @param string$header
     * @return string|array|null
     */
    public function getHeader($header);

    /**
     * Get all headers as string
     *
     * @param boolean $status_line Whether to return the first status line (IE "HTTP 200 OK")
     * @param string $br Line breaks (eg. "\n", "\r\n", "<br />")
     * @return string
     */
    public function getHeadersAsString($status_line = true, $br = "\n");

    /**
     * Get the entire response as string
     *
     * @param string $br Line breaks (eg. "\n", "\r\n", "<br />")
     * @return string
     */
    public function asString($br = "\n");
    
    /**
     * Stringify the object - basically a wrapper for ::asString()
     *
     * @return string
     */
    public function __toString();

    /**
     * A convenience function that returns a text representation of
     * HTTP response codes. Returns null for unknown codes.
     *
     * Conforms to HTTP/1.1 as defined in RFC 2616
     * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 for reference
     * 
     * @param int $code HTTP response code
     * @param boolean $http11 Use HTTP version 1.1 
     * @return string|null
     */ 
    static public function responseCodeAsText($code, $http11 = true);

    /**
     * Extract the response code from a response string
     *
     * @param string $response_str
     * @return int
     */
    static public function extractCode($response_str);

    /**
     * Extract the HTTP message from a response
     *
     * @param string $response_str
     * @return string
     */
    static public function extractMessage($response_str);

    /**
     * Extract the HTTP version from a response
     *
     * @param string $response_str
     * @return string
     */
    static public function extractVersion($response_str);

    /**
     * Extract the headers from a response string
     *
     * @param string $response_str
     * @return array
     */
    static public function extractHeaders($response_str);

    /**
     * Extract the body from a response string
     *
     * @param string $response_str
     * @return string
     */
    static public function extractBody($response_str);

    /**
     * Decode a "chunked" transfer-encoded body and return the decoded text
     *
     * @param string $body
     * @return string
     */
    static public function decodeChunkedBody($body);
    
    /**
     * Decode a gzip encoded message (when Content-encoding = gzip)
     *
     * Currently requires PHP with zlib support
     * 
     * @param string $body
     * @return string
     */
    static public function decodeGzip($body);

    /**
     * Decode a zlib deflated message (when Content-encoding = deflate)
     *
     * Currently requires PHP with zlib support
     * 
     * @param string $body
     * @return string
     */
    static public function decodeDeflate($body);
    
    /**
     * Create a new Zend_Http_Response object from a string
     *
     * @param string $response_str
     * @return Zend_Http_Response
     */
    static public function factory($response_str);
}

<?php

class Zend_Http_Cookie 
{    
    /**
     * Cookie name
     *
     * @var string
     */
    protected $name;
    
    /**
     * Cookie value
     *
     * @var string
     */
    protected $value;
    
    /**
     * Cookie expiry date
     *
     * @var int
     */
    protected $expires;
    
    /**
     * Cookie domain
     *
     * @var string
     */
    protected $domain;
    
    /**
     * Cookie path
     *
     * @var string
     */
    protected $path;
    
    /**
     * Whether the cookie is secure or not
     *
     * @var boolean
     */
    protected $secure;
    
    /**
     * Cookie object constructor
     * 
     * @todo Add validation of each one of the parameters (legal domain, etc.)
     *  
     * @param string $name
     * @param string $value
     * @param int $expires
     * @param string $domain
     * @param string $path
     * @param bool $secure
     */
    public function __construct($name, $value, $domain, $expires = null, $path = null, $secure = false);
    
    /**
     * Get Cookie name
     *
     * @return string
     */
    public function getName();
    
    /**
     * Get cookie value
     *
     * @return string
     */
    public function getValue();
    
    /**
     * Get cookie domain
     *
     * @return string
     */
    public function getDomain();
    
    /**
     * Get the cookie path 
     *
     * @return string
     */
    public function getPath();
    
    /**
     * Get the expiry time of the cookie, or null if no expiry time is set
     *
     * @return int|null
     */
    public function getExpiryTime();
    
    /**
     * Check whether the cookie should only be sent over secure connections
     *
     * @return boolean
     */
    public function isSecure();
    
    /**
     * Check whether the cookie has expired
     * 
     * Always returns true if the cookie is a session cookie (has no expiry time)
     *
     * @param int $now Timestamp to consider as "now"
     * @return boolean
     */
    public function isExpired($now = null);
    
    /**
     * Check whether the cookie is a session cookie (has no expiry time set)
     *
     * @return boolean
     */
    public function isSessionCookie();
    
    /**
     * Get the cookie as a string, suitable for sending as a "Cookie" header in an 
     * HTTP request
     *
     * @return string
     */
    public function __toString();
	
    /**
     * Checks whether the cookie should be sent on not in a specific scenario
     *
     * @param string|Zend_Uri_Http $uri URI to check against (secure, domain, path)
     * @param boolean $matchSessionCookies Whether to send session cookies
     * @param int $now Override the current time when checking for expiry time
     * @return boolean
     */
    public function match($uri, $matchSessionCookies = true, $now = null);
    
    /**
     * Generate a new Cookie object from a cookie string 
     * (for example the value of the Set-Cookie HTTP header)
     *
     * @param string $cookieStr
     * @param Zend_Uri_Http|string $ref_uri Reference URI for default values (domain, path)
     * @return Zend_Http_Cookie A new Zend_Http_Cookie object or false on failure.
     */
    static public function factory($cookieStr, $ref_uri = null);
}

<?php

/**
 * @see http://wp.netscape.com/newsref/std/cookie_spec.html
 */
class Zend_Http_Cookiejar
{
    /**
     * Cookie return form constants
     */
    
    // Return cookie(s) as a Zend_Http_Cookie object
    const COOKIE_OBJECT = 0;

    // Return cookie(s) as a string (suitable for sending in an HTTP request)
    const COOKIE_STRING_ARRAY = 1;
    
    // Return all cookies as one long string (suitable for sending in an HTTP request)
    const COOKIE_STRING_CONCAT = 2;
    
    /**
     * Array storing cookies
     * 
     * Cookies are stored according to domain and path:
     * $cookies
     *  + www.mydomain.com
     *    + /
     *      - cookie1 
     *      - cookie2
     *    + /somepath
     *      - othercookie
     *  + www.otherdomain.net
     *    + /
     *      - alsocookie
     *
     * @var array
     */
    protected $cookies = array();
    
    /**
     * Construct a new CookieJar object
     *
     */
    public function __construct();
    
    /**
     * Add a cookie to the jar. Cookie should be passed either as a Zend_Http_Cookie object
     * or as a string - in which case an object is created from the string.
     *
     * @param Zend_Http_Cookie|string $cookie
     * @param Zend_Uri_Http|string $red_uri Optional reference URI (for domain, path, secure)
     */
    public function addCookie($cookie, $ref_uri = null);
    
    /**
     * Parse an HTTP response, adding all the cookies set in that response
     * to the cookie jar.
     *
     * @param Zend_Http_Response $response
     * @param Zend_Uri_Http|string $ref_uri Requested URI
     */
    public function addCookiesFromResponse($response, $ref_uri);
    
    /**
     * Get all cookies in the cookie jar as an array
     *
     * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
     * @return array|string
     */
    public function getAllCookies($ret_as = self::COOKIE_OBJECT);
    
    /**
     * Return an array of all cookies matching a specific request according to the request URI,
     * whether session cookies should be sent or not, and the time to consider as "now" when
     * checking cookie expiry time.
     *
     * @param string|Zend_Uri_Http $uri URI to check against (secure, domain, path)
     * @param boolean $matchSessionCookies Whether to send session cookies
     * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
     * @param int $now Override the current time when checking for expiry time
     * @return array|string
     */
    public function getMatchingCookies($uri, $matchSessionCookies = true, 
        $ret_as = self::COOKIE_OBJECT, $now = null);
    
    /**
     * Get a specific cookie according to a URI and name
     *
     * @param Zend_Uri_Http|string $uri The uri (domain and path) to match
     * @param string $cookie_name The cookie's name
     * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
     * @return Zend_Http_Cookie|string
     */
    public function getCookie($uri, $cookie_name, $ret_as = self::COOKIE_OBJECT);
    
    /**
     * Remove all cookies from the jar
     *
     */
    public function deleteAllCookies();
    
    /**
     * Clear all cookies who's expiry time is older than $time
     *
     * @param int $time Expiry time (default is now)
     */
    public function deleteExpiredCookies($time = null);
    
    /**
     * Clear "Session" cookies (cookies without specific expiry time)
     *
     */
    public function deleteSessionCookies();
    
    /**
     * Delete a cookie according to it's name and domain. If no name is specified,
     * all cookies from this domain will be cleared out.
     *
     * @param string|Zend_Uri_Http $domain
     * @param string $cookie_name 
     * @return boolean true if cookie was deleted.
     */
    public function deleteCookies($domain, $cookie_name = null);
    
    /**
     * Helper function to recursivly flatten an array. Shoud be used when exporting the 
     * cookies array (or parts of it)
     *
     * @param Zend_Http_Cookie|array $ptr
     * @param int $ret_as What value to return
     * @return array|string
     */
    protected function _flattenCookiesArray($ptr, $ret_as = self::COOKIE_OBJECT);
    
    /**
     * Return a subset of the cookies array matching a specific domain
     * 
     * Returned array is actually an array of pointers to items in the $this->cookies array.
     *
     * @param string $domain
     * @return array
     */
    protected function _matchDomain($domain);
    
    /**
     * Return a subset of a domain-matching cookies that also match a specified path
     *
     * Returned array is actually an array of pointers to items in the $passed array.
     * 
     * @param array $dom_array
     * @param string $path
     * @return array
     */
    protected function _matchPath($domains, $path);
    
    /**
     * Create a new CookieJar object and automatically load into it all the 
     * cookies set in an Http_Response object. If $uri is set, it will be 
     * considered as the requested URI for setting default domain and path
     * of the cookie.
     *
     * @param Zend_Http_Response $response HTTP Response object
     * @param Zend_Uri_Http|string $uri The requested URI 
     * @return Zend_Http_Cookiejar
     * @todo Add the $uri functionality. 
     */
    static public function factory(Zend_Http_Response $response, $ref_uri);
}

Page Operations

Browse Space

Zend_Http_Client - Shahar Evron

Labels

Zend Framework: Zend_Http_Client Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria