<?php
/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to version 1.0 of the Zend Framework
 * license, that is bundled with this package in the file LICENSE.txt,
 * and is available through the world-wide-web at the following URL:
 * http://framework.zend.com/license/new-bsd. If you did not
 * receive a copy of the Zend Framework license and are unable to
 * obtain it through the world-wide-web, please send a note to
 * license@zend.com so we can mail you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Http
 * @subpackage CookieJar
 * @version    $Id: CookieJar.php 8064 2008-02-16 10:58:39Z thomas $
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com/)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */

require_once "Zend/Uri.php";
require_once "Zend/Http/Cookie.php";
require_once "Zend/Http/Response.php";

/**
 * A Zend_Http_CookieJar object is designed to contain and maintain HTTP cookies, and should
 * be used along with Zend_Http_Client in order to manage cookies across HTTP requests and
 * responses.
 *
 * The class contains an array of Zend_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 Zend_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 Zend_Http_CookieJar::COOKIE_STRING_ARRAY) or one unified string for all cookies
 * (by passing Zend_Http_CookieJar::COOKIE_STRING_CONCAT).
 *
 * @link       http://wp.netscape.com/newsref/std/cookie_spec.html for some specs.
 * 
 * @category   Zend
 * @package    Zend_Http
 * @subpackage CookieJar
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com/)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Http_CookieJar {
  /**
   * 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    $ref_uri Optional reference URI (for domain, path, secure)
   */
  public function addCookie($cookie, $ref_uri = null) {
    if (is_string($cookie)) {
      $cookie = Zend_Http_Cookie::fromString($cookie, $ref_uri);
    }
    
    if ($cookie instanceof Zend_Http_Cookie) {
      $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;
    } else {
      require_once 'external/Zend/Http/Exception.php';
      throw new Zend_Http_Exception('Supplient argument is not a valid cookie string or object');
    }
  }

  /**
   * 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) {
    if (! $response instanceof Zend_Http_Response) {
      require_once 'external/Zend/Http/Exception.php';
      throw new Zend_Http_Exception('$response is expected to be a Response object, ' . gettype($response) . ' was passed');
    }
    
    $cookie_hdrs = $response->getHeader('Set-Cookie');
    
    if (is_array($cookie_hdrs)) {
      foreach ($cookie_hdrs as $cookie) {
        $this->addCookie($cookie, $ref_uri);
      }
    } elseif (is_string($cookie_hdrs)) {
      $this->addCookie($cookie_hdrs, $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) {
    $cookies = $this->_flattenCookiesArray($this->cookies, $ret_as);
    return $cookies;
  }

  /**
   * 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) {
    if (is_string($uri)) $uri = Zend_Uri::factory($uri);
    if (! $uri instanceof Zend_Uri_Http) {
      require_once 'external/Zend/Http/Exception.php';
      throw new Zend_Http_Exception("Invalid URI string or object passed");
    }
    
    // Set path
    $path = $uri->getPath();
    $path = substr($path, 0, strrpos($path, '/'));
    if (! $path) $path = '/';
    
    // First, reduce the array of cookies to only those matching domain and path
    $cookies = $this->_matchDomain($uri->getHost());
    $cookies = $this->_matchPath($cookies, $path);
    $cookies = $this->_flattenCookiesArray($cookies, self::COOKIE_OBJECT);
    
    // Next, run Cookie->match on all cookies to check secure, time and session mathcing
    $ret = array();
    foreach ($cookies as $cookie)
      if ($cookie->match($uri, $matchSessionCookies, $now)) $ret[] = $cookie;
      
    // Now, use self::_flattenCookiesArray again - only to convert to the return format ;)
    $ret = $this->_flattenCookiesArray($ret, $ret_as);
    
    return $ret;
  }

  /**
   * 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) {
    if (is_string($uri)) {
      $uri = Zend_Uri::factory($uri);
    }
    
    if (! $uri instanceof Zend_Uri_Http) {
      require_once 'external/Zend/Http/Exception.php';
      throw new Zend_Http_Exception('Invalid URI specified');
    }
    
    // Get correct cookie path
    $path = $uri->getPath();
    $path = substr($path, 0, strrpos($path, '/'));
    if (! $path) $path = '/';
    
    if (isset($this->cookies[$uri->getHost()][$path][$cookie_name])) {
      $cookie = $this->cookies[$uri->getHost()][$path][$cookie_name];
      
      switch ($ret_as) {
        case self::COOKIE_OBJECT:
          return $cookie;
          break;
        
        case self::COOKIE_STRING_ARRAY:
        case self::COOKIE_STRING_CONCAT:
          return $cookie->__toString();
          break;
        
        default:
          require_once 'external/Zend/Http/Exception.php';
          throw new Zend_Http_Exception("Invalid value passed for \$ret_as: {$ret_as}");
          break;
      }
    } else {
      return false;
    }
  }

  /**
   * 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) {
    if (is_array($ptr)) {
      $ret = ($ret_as == self::COOKIE_STRING_CONCAT ? '' : array());
      foreach ($ptr as $item) {
        if ($ret_as == self::COOKIE_STRING_CONCAT) {
          $ret .= $this->_flattenCookiesArray($item, $ret_as);
        } else {
          $ret = array_merge($ret, $this->_flattenCookiesArray($item, $ret_as));
        }
      }
      return $ret;
    } elseif ($ptr instanceof Zend_Http_Cookie) {
      switch ($ret_as) {
        case self::COOKIE_STRING_ARRAY:
          return array($ptr->__toString());
          break;
        
        case self::COOKIE_STRING_CONCAT:
          return $ptr->__toString();
          break;
        
        case self::COOKIE_OBJECT:
        default:
          return array($ptr);
          break;
      }
    }
    
    return null;
  }

  /**
   * 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) {
    $ret = array();
    
    foreach (array_keys($this->cookies) as $cdom) {
      $regex = "/" . preg_quote($cdom, "/") . "$/i";
      if (preg_match($regex, $domain)) $ret[$cdom] = &$this->cookies[$cdom];
    }
    
    return $ret;
  }

  /**
   * 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) {
    $ret = array();
    if (substr($path, - 1) != '/') $path .= '/';
    
    foreach ($domains as $dom => $paths_array) {
      foreach (array_keys($paths_array) as $cpath) {
        $regex = "|^" . preg_quote($cpath, "|") . "|i";
        if (preg_match($regex, $path)) {
          if (! isset($ret[$dom])) $ret[$dom] = array();
          $ret[$dom][$cpath] = &$paths_array[$cpath];
        }
      }
    }
    
    return $ret;
  }

  /**
   * 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.
   */
  public static function fromResponse(Zend_Http_Response $response, $ref_uri) {
    $jar = new self();
    $jar->addCookiesFromResponse($response, $ref_uri);
    return $jar;
  }
}