[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Zend Framework
   4   *
   5   * LICENSE
   6   *
   7   * This source file is subject to the new BSD license that is bundled
   8   * with this package in the file LICENSE.txt.
   9   * It is also available through the world-wide-web at this URL:
  10   * http://framework.zend.com/license/new-bsd
  11   * If you did not receive a copy of the license and are unable to
  12   * obtain it through the world-wide-web, please send an email
  13   * to [email protected] so we can send you a copy immediately.
  14   *
  15   * @category   Zend
  16   * @package    Zend_Http
  17   * @subpackage CookieJar
  18   * @version    $Id$
  19   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21   */
  22  
  23  /**
  24   * @see Zend_Uri
  25   */
  26  require_once "Zend/Uri.php";
  27  /**
  28   * @see Zend_Http_Cookie
  29   */
  30  require_once "Zend/Http/Cookie.php";
  31  /**
  32   * @see Zend_Http_Response
  33   */
  34  require_once "Zend/Http/Response.php";
  35  
  36  /**
  37   * A Zend_Http_CookieJar object is designed to contain and maintain HTTP cookies, and should
  38   * be used along with Zend_Http_Client in order to manage cookies across HTTP requests and
  39   * responses.
  40   *
  41   * The class contains an array of Zend_Http_Cookie objects. Cookies can be added to the jar
  42   * automatically from a request or manually. Then, the jar can find and return the cookies
  43   * needed for a specific HTTP request.
  44   *
  45   * A special parameter can be passed to all methods of this class that return cookies: Cookies
  46   * can be returned either in their native form (as Zend_Http_Cookie objects) or as strings -
  47   * the later is suitable for sending as the value of the "Cookie" header in an HTTP request.
  48   * You can also choose, when returning more than one cookie, whether to get an array of strings
  49   * (by passing Zend_Http_CookieJar::COOKIE_STRING_ARRAY) or one unified string for all cookies
  50   * (by passing Zend_Http_CookieJar::COOKIE_STRING_CONCAT).
  51   *
  52   * @link       http://wp.netscape.com/newsref/std/cookie_spec.html for some specs.
  53   *
  54   * @category   Zend
  55   * @package    Zend_Http
  56   * @subpackage CookieJar
  57   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  58   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  59   */
  60  class Zend_Http_CookieJar implements Countable, IteratorAggregate
  61  {
  62      /**
  63       * Return cookie(s) as a Zend_Http_Cookie object
  64       *
  65       */
  66      const COOKIE_OBJECT = 0;
  67  
  68      /**
  69       * Return cookie(s) as a string (suitable for sending in an HTTP request)
  70       *
  71       */
  72      const COOKIE_STRING_ARRAY = 1;
  73  
  74      /**
  75       * Return all cookies as one long string (suitable for sending in an HTTP request)
  76       *
  77       */
  78      const COOKIE_STRING_CONCAT = 2;
  79  
  80      /**
  81       * Array storing cookies
  82       *
  83       * Cookies are stored according to domain and path:
  84       * $cookies
  85       *  + www.mydomain.com
  86       *    + /
  87       *      - cookie1
  88       *      - cookie2
  89       *    + /somepath
  90       *      - othercookie
  91       *  + www.otherdomain.net
  92       *    + /
  93       *      - alsocookie
  94       *
  95       * @var array
  96       */
  97      protected $cookies = array();
  98  
  99      /**
 100       * The Zend_Http_Cookie array
 101       *
 102       * @var array
 103       */
 104      protected $_rawCookies = array();
 105  
 106      /**
 107       * Construct a new CookieJar object
 108       *
 109       */
 110      public function __construct()
 111      { }
 112  
 113      /**
 114       * Add a cookie to the jar. Cookie should be passed either as a Zend_Http_Cookie object
 115       * or as a string - in which case an object is created from the string.
 116       *
 117       * @param Zend_Http_Cookie|string $cookie
 118       * @param Zend_Uri_Http|string    $ref_uri Optional reference URI (for domain, path, secure)
 119       */
 120      public function addCookie($cookie, $ref_uri = null)
 121      {
 122          if (is_string($cookie)) {
 123              $cookie = Zend_Http_Cookie::fromString($cookie, $ref_uri);
 124          }
 125  
 126          if ($cookie instanceof Zend_Http_Cookie) {
 127              $domain = $cookie->getDomain();
 128              $path = $cookie->getPath();
 129              if (! isset($this->cookies[$domain])) $this->cookies[$domain] = array();
 130              if (! isset($this->cookies[$domain][$path])) $this->cookies[$domain][$path] = array();
 131              $this->cookies[$domain][$path][$cookie->getName()] = $cookie;
 132              $this->_rawCookies[] = $cookie;
 133          } else {
 134              require_once 'Zend/Http/Exception.php';
 135              throw new Zend_Http_Exception('Supplient argument is not a valid cookie string or object');
 136          }
 137      }
 138  
 139      /**
 140       * Parse an HTTP response, adding all the cookies set in that response
 141       * to the cookie jar.
 142       *
 143       * @param Zend_Http_Response $response
 144       * @param Zend_Uri_Http|string $ref_uri Requested URI
 145       */
 146      public function addCookiesFromResponse($response, $ref_uri)
 147      {
 148          if (! $response instanceof Zend_Http_Response) {
 149              require_once 'Zend/Http/Exception.php';
 150              throw new Zend_Http_Exception('$response is expected to be a Response object, ' .
 151                  gettype($response) . ' was passed');
 152          }
 153  
 154          $cookie_hdrs = $response->getHeader('Set-Cookie');
 155  
 156          if (is_array($cookie_hdrs)) {
 157              foreach ($cookie_hdrs as $cookie) {
 158                  $this->addCookie($cookie, $ref_uri);
 159              }
 160          } elseif (is_string($cookie_hdrs)) {
 161              $this->addCookie($cookie_hdrs, $ref_uri);
 162          }
 163      }
 164  
 165      /**
 166       * Get all cookies in the cookie jar as an array
 167       *
 168       * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
 169       * @return array|string
 170       */
 171      public function getAllCookies($ret_as = self::COOKIE_OBJECT)
 172      {
 173          $cookies = $this->_flattenCookiesArray($this->cookies, $ret_as);
 174          return $cookies;
 175      }
 176  
 177      /**
 178       * Return an array of all cookies matching a specific request according to the request URI,
 179       * whether session cookies should be sent or not, and the time to consider as "now" when
 180       * checking cookie expiry time.
 181       *
 182       * @param string|Zend_Uri_Http $uri URI to check against (secure, domain, path)
 183       * @param boolean $matchSessionCookies Whether to send session cookies
 184       * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
 185       * @param int $now Override the current time when checking for expiry time
 186       * @return array|string
 187       */
 188      public function getMatchingCookies($uri, $matchSessionCookies = true,
 189          $ret_as = self::COOKIE_OBJECT, $now = null)
 190      {
 191          if (is_string($uri)) $uri = Zend_Uri::factory($uri);
 192          if (! $uri instanceof Zend_Uri_Http) {
 193              require_once 'Zend/Http/Exception.php';
 194              throw new Zend_Http_Exception("Invalid URI string or object passed");
 195          }
 196  
 197          // First, reduce the array of cookies to only those matching domain and path
 198          $cookies = $this->_matchDomain($uri->getHost());
 199          $cookies = $this->_matchPath($cookies, $uri->getPath());
 200          $cookies = $this->_flattenCookiesArray($cookies, self::COOKIE_OBJECT);
 201  
 202          // Next, run Cookie->match on all cookies to check secure, time and session mathcing
 203          $ret = array();
 204          foreach ($cookies as $cookie)
 205              if ($cookie->match($uri, $matchSessionCookies, $now))
 206                  $ret[] = $cookie;
 207  
 208          // Now, use self::_flattenCookiesArray again - only to convert to the return format ;)
 209          $ret = $this->_flattenCookiesArray($ret, $ret_as);
 210  
 211          return $ret;
 212      }
 213  
 214      /**
 215       * Get a specific cookie according to a URI and name
 216       *
 217       * @param Zend_Uri_Http|string $uri The uri (domain and path) to match
 218       * @param string $cookie_name The cookie's name
 219       * @param int $ret_as Whether to return cookies as objects of Zend_Http_Cookie or as strings
 220       * @return Zend_Http_Cookie|string
 221       */
 222      public function getCookie($uri, $cookie_name, $ret_as = self::COOKIE_OBJECT)
 223      {
 224          if (is_string($uri)) {
 225              $uri = Zend_Uri::factory($uri);
 226          }
 227  
 228          if (! $uri instanceof Zend_Uri_Http) {
 229              require_once 'Zend/Http/Exception.php';
 230              throw new Zend_Http_Exception('Invalid URI specified');
 231          }
 232  
 233          // Get correct cookie path
 234          $path = $uri->getPath();
 235          $path = substr($path, 0, strrpos($path, '/'));
 236          if (! $path) $path = '/';
 237  
 238          if (isset($this->cookies[$uri->getHost()][$path][$cookie_name])) {
 239              $cookie = $this->cookies[$uri->getHost()][$path][$cookie_name];
 240  
 241              switch ($ret_as) {
 242                  case self::COOKIE_OBJECT:
 243                      return $cookie;
 244                      break;
 245  
 246                  case self::COOKIE_STRING_ARRAY:
 247                  case self::COOKIE_STRING_CONCAT:
 248                      return $cookie->__toString();
 249                      break;
 250  
 251                  default:
 252                      require_once 'Zend/Http/Exception.php';
 253                      throw new Zend_Http_Exception("Invalid value passed for \$ret_as: {$ret_as}");
 254                      break;
 255              }
 256          } else {
 257              return false;
 258          }
 259      }
 260  
 261      /**
 262       * Helper function to recursivly flatten an array. Shoud be used when exporting the
 263       * cookies array (or parts of it)
 264       *
 265       * @param Zend_Http_Cookie|array $ptr
 266       * @param int $ret_as What value to return
 267       * @return array|string
 268       */
 269      protected function _flattenCookiesArray($ptr, $ret_as = self::COOKIE_OBJECT) {
 270          if (is_array($ptr)) {
 271              $ret = ($ret_as == self::COOKIE_STRING_CONCAT ? '' : array());
 272              foreach ($ptr as $item) {
 273                  if ($ret_as == self::COOKIE_STRING_CONCAT) {
 274                      $ret .= $this->_flattenCookiesArray($item, $ret_as);
 275                  } else {
 276                      $ret = array_merge($ret, $this->_flattenCookiesArray($item, $ret_as));
 277                  }
 278              }
 279              return $ret;
 280          } elseif ($ptr instanceof Zend_Http_Cookie) {
 281              switch ($ret_as) {
 282                  case self::COOKIE_STRING_ARRAY:
 283                      return array($ptr->__toString());
 284                      break;
 285  
 286                  case self::COOKIE_STRING_CONCAT:
 287                      return $ptr->__toString();
 288                      break;
 289  
 290                  case self::COOKIE_OBJECT:
 291                  default:
 292                      return array($ptr);
 293                      break;
 294              }
 295          }
 296  
 297          return null;
 298      }
 299  
 300      /**
 301       * Return a subset of the cookies array matching a specific domain
 302       *
 303       * @param string $domain
 304       * @return array
 305       */
 306      protected function _matchDomain($domain)
 307      {
 308          $ret = array();
 309  
 310          foreach (array_keys($this->cookies) as $cdom) {
 311              if (Zend_Http_Cookie::matchCookieDomain($cdom, $domain)) {
 312                  $ret[$cdom] = $this->cookies[$cdom];
 313              }
 314          }
 315  
 316          return $ret;
 317      }
 318  
 319      /**
 320       * Return a subset of a domain-matching cookies that also match a specified path
 321       *
 322       * @param array $dom_array
 323       * @param string $path
 324       * @return array
 325       */
 326      protected function _matchPath($domains, $path)
 327      {
 328          $ret = array();
 329  
 330          foreach ($domains as $dom => $paths_array) {
 331              foreach (array_keys($paths_array) as $cpath) {
 332                  if (Zend_Http_Cookie::matchCookiePath($cpath, $path)) {
 333                      if (! isset($ret[$dom])) {
 334                          $ret[$dom] = array();
 335                      }
 336  
 337                      $ret[$dom][$cpath] = $paths_array[$cpath];
 338                  }
 339              }
 340          }
 341  
 342          return $ret;
 343      }
 344  
 345      /**
 346       * Create a new CookieJar object and automatically load into it all the
 347       * cookies set in an Http_Response object. If $uri is set, it will be
 348       * considered as the requested URI for setting default domain and path
 349       * of the cookie.
 350       *
 351       * @param Zend_Http_Response $response HTTP Response object
 352       * @param Zend_Uri_Http|string $uri The requested URI
 353       * @return Zend_Http_CookieJar
 354       * @todo Add the $uri functionality.
 355       */
 356      public static function fromResponse(Zend_Http_Response $response, $ref_uri)
 357      {
 358          $jar = new self();
 359          $jar->addCookiesFromResponse($response, $ref_uri);
 360          return $jar;
 361      }
 362  
 363      /**
 364       * Required by Countable interface
 365       *
 366       * @return int
 367       */
 368      public function count()
 369      {
 370          return count($this->_rawCookies);
 371      }
 372  
 373      /**
 374       * Required by IteratorAggregate interface
 375       *
 376       * @return ArrayIterator
 377       */
 378      public function getIterator()
 379      {
 380          return new ArrayIterator($this->_rawCookies);
 381      }
 382  
 383      /**
 384       * Tells if the jar is empty of any cookie
 385       *
 386       * @return bool
 387       */
 388      public function isEmpty()
 389      {
 390          return count($this) == 0;
 391      }
 392  
 393      /**
 394       * Empties the cookieJar of any cookie
 395       *
 396       * @return Zend_Http_CookieJar
 397       */
 398      public function reset()
 399      {
 400          $this->cookies = $this->_rawCookies = array();
 401          return $this;
 402      }
 403  }