Source for file CookieJar.php
Documentation is available at CookieJar.php
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
* @package Microsoft_Http
* @version $Id: CookieJar.php 17131 2009-07-26 10:03:39Z shahar $
* @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @see Microsoft_AutoLoader
require_once dirname(__FILE__ ) . '/../AutoLoader.php';
* A Microsoft_Http_CookieJar object is designed to contain and maintain HTTP cookies, and should
* be used along with Microsoft_Http_Client in order to manage cookies across HTTP requests and
* The class contains an array of Microsoft_Http_Cookie objects. Cookies can be added to the jar
* automatically from a request or manually. Then, the jar can find and return the cookies
* needed for a specific HTTP request.
* A special parameter can be passed to all methods of this class that return cookies: Cookies
* can be returned either in their native form (as Microsoft_Http_Cookie objects) or as strings -
* the later is suitable for sending as the value of the "Cookie" header in an HTTP request.
* You can also choose, when returning more than one cookie, whether to get an array of strings
* (by passing Microsoft_Http_CookieJar::COOKIE_STRING_ARRAY) or one unified string for all cookies
* (by passing Microsoft_Http_CookieJar::COOKIE_STRING_CONCAT).
* @link http://wp.netscape.com/newsref/std/cookie_spec.html for some specs.
* @package Microsoft_Http
* @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* Return cookie(s) as a Microsoft_Http_Cookie object
* 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;
* Cookies are stored according to domain and path:
* The Microsoft_Http_Cookie array
* Construct a new CookieJar object
* Add a cookie to the jar. Cookie should be passed either as a Microsoft_Http_Cookie object
* or as a string - in which case an object is created from the string.
* @param Microsoft_Http_Cookie|string$cookie
* @param Microsoft_Uri_Http|string $ref_uri Optional reference URI (for domain, path, secure)
public function addCookie($cookie, $ref_uri = null)
$domain = $cookie->getDomain();
$path = $cookie->getPath();
if (! isset ($this->cookies[$domain])) $this->cookies[$domain] = array();
if (! isset ($this->cookies[$domain][$path])) $this->cookies[$domain][$path] = array();
$this->cookies[$domain][$path][$cookie->getName()] = $cookie;
require_once 'Microsoft/Http/Exception.php';
* Parse an HTTP response, adding all the cookies set in that response
* @param Microsoft_Http_Response $response
* @param Microsoft_Uri_Http|string$ref_uri Requested URI
require_once 'Microsoft/Http/Exception.php';
gettype($response) . ' was passed');
$cookie_hdrs = $response->getHeader('Set-Cookie');
foreach ($cookie_hdrs as $cookie) {
* Get all cookies in the cookie jar as an array
* @param int $ret_as Whether to return cookies as objects of Microsoft_Http_Cookie or as strings
* 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|Microsoft_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 Microsoft_Http_Cookie or as strings
* @param int $now Override the current time when checking for expiry time
$ret_as = self::COOKIE_OBJECT, $now = null)
require_once 'Microsoft/Http/Exception.php';
// First, reduce the array of cookies to only those matching domain and path
$cookies = $this->_matchPath($cookies, $uri->getPath());
// Next, run Cookie->match on all cookies to check secure, time and session mathcing
foreach ($cookies as $cookie)
if ($cookie->match($uri, $matchSessionCookies, $now))
// Now, use self::_flattenCookiesArray again - only to convert to the return format ;)
* Get a specific cookie according to a URI and name
* @param Microsoft_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 Microsoft_Http_Cookie or as strings
* @return Microsoft_Http_Cookie|string
public function getCookie($uri, $cookie_name, $ret_as = self::COOKIE_OBJECT)
require_once 'Microsoft/Http/Exception.php';
// Get correct cookie path
if (! $path) $path = '/';
if (isset ($this->cookies[$uri->getHost()][$path][$cookie_name])) {
$cookie = $this->cookies[$uri->getHost()][$path][$cookie_name];
case self::COOKIE_OBJECT:
case self::COOKIE_STRING_ARRAY:
case self::COOKIE_STRING_CONCAT:
return $cookie->__toString();
require_once 'Microsoft/Http/Exception.php';
* Helper function to recursivly flatten an array. Shoud be used when exporting the
* cookies array (or parts of it)
* @param Microsoft_Http_Cookie|array$ptr
* @param int $ret_as What value to return
$ret = ($ret_as == self::COOKIE_STRING_CONCAT ? '' : array());
foreach ($ptr as $item) {
if ($ret_as == self::COOKIE_STRING_CONCAT) {
case self::COOKIE_STRING_ARRAY:
return array($ptr->__toString());
case self::COOKIE_STRING_CONCAT:
return $ptr->__toString();
case self::COOKIE_OBJECT:
* Return a subset of the cookies array matching a specific domain
$ret[$cdom] = $this->cookies[$cdom];
* Return a subset of a domain-matching cookies that also match a specified path
* @param array $dom_array
foreach ($domains as $dom => $paths_array) {
if (! isset ($ret[$dom])) {
$ret[$dom][$cpath] = $paths_array[$cpath];
* 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
* @param Microsoft_Http_Response $response HTTP Response object
* @param Microsoft_Uri_Http|string$uri The requested URI
* @return Microsoft_Http_CookieJar
* @todo Add the $uri functionality.
public static function fromResponse(Microsoft_Http_Response $response, $ref_uri)
$jar->addCookiesFromResponse($response, $ref_uri);
* Required by Countable interface
* Required by IteratorAggregate interface
* Tells if the jar is empty of any cookie
return count($this) == 0;
* Empties the cookieJar of any cookie
* @return Microsoft_Http_CookieJar
|