*\r
* LICENSE:\r
*\r
- * Copyright (c) 2008-2011, Alexey Borzov <avb@php.net>\r
+ * Copyright (c) 2008-2012, Alexey Borzov <avb@php.net>\r
* All rights reserved.\r
*\r
* Redistribution and use in source and binary forms, with or without\r
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\r
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
*\r
- * @category HTTP\r
- * @package HTTP_Request2\r
- * @author Alexey Borzov <avb@php.net>\r
- * @license http://opensource.org/licenses/bsd-license.php New BSD License\r
- * @version SVN: $Id: CookieJar.php 308629 2011-02-24 17:34:24Z avb $\r
- * @link http://pear.php.net/package/HTTP_Request2\r
+ * @category HTTP\r
+ * @package HTTP_Request2\r
+ * @author Alexey Borzov <avb@php.net>\r
+ * @license http://opensource.org/licenses/bsd-license.php New BSD License\r
+ * @version SVN: $Id: CookieJar.php 324415 2012-03-21 10:50:50Z avb $\r
+ * @link http://pear.php.net/package/HTTP_Request2\r
*/\r
\r
/** Class representing a HTTP request message */\r
/**\r
* Stores cookies and passes them between HTTP requests\r
*\r
- * @category HTTP\r
- * @package HTTP_Request2\r
- * @author Alexey Borzov <avb@php.net>\r
- * @version Release: @package_version@\r
+ * @category HTTP\r
+ * @package HTTP_Request2\r
+ * @author Alexey Borzov <avb@php.net>\r
+ * @license http://opensource.org/licenses/bsd-license.php New BSD License\r
+ * @version Release: @package_version@\r
+ * @link http://pear.php.net/package/HTTP_Request2\r
*/\r
class HTTP_Request2_CookieJar implements Serializable\r
{\r
- /**\r
- * Array of stored cookies\r
- *\r
- * The array is indexed by domain, path and cookie name\r
- * .example.com\r
- * /\r
- * some_cookie => cookie data\r
- * /subdir\r
- * other_cookie => cookie data\r
- * .example.org\r
- * ...\r
- *\r
- * @var array\r
- */\r
+ /**\r
+ * Array of stored cookies\r
+ *\r
+ * The array is indexed by domain, path and cookie name\r
+ * .example.com\r
+ * /\r
+ * some_cookie => cookie data\r
+ * /subdir\r
+ * other_cookie => cookie data\r
+ * .example.org\r
+ * ...\r
+ *\r
+ * @var array\r
+ */\r
protected $cookies = array();\r
\r
- /**\r
- * Whether session cookies should be serialized when serializing the jar\r
- * @var bool\r
- */\r
+ /**\r
+ * Whether session cookies should be serialized when serializing the jar\r
+ * @var bool\r
+ */\r
protected $serializeSession = false;\r
\r
- /**\r
- * Whether Public Suffix List should be used for domain matching\r
- * @var bool\r
- */\r
+ /**\r
+ * Whether Public Suffix List should be used for domain matching\r
+ * @var bool\r
+ */\r
protected $useList = true;\r
\r
- /**\r
- * Array with Public Suffix List data\r
- * @var array\r
- * @link http://publicsuffix.org/\r
- */\r
+ /**\r
+ * Array with Public Suffix List data\r
+ * @var array\r
+ * @link http://publicsuffix.org/\r
+ */\r
protected static $psl = array();\r
\r
- /**\r
- * Class constructor, sets various options\r
- *\r
- * @param bool Controls serializing session cookies, see {@link serializeSessionCookies()}\r
- * @param bool Controls using Public Suffix List, see {@link usePublicSuffixList()}\r
- */\r
- public function __construct($serializeSessionCookies = false, $usePublicSuffixList = true)\r
- {\r
+ /**\r
+ * Class constructor, sets various options\r
+ *\r
+ * @param bool $serializeSessionCookies Controls serializing session cookies,\r
+ * see {@link serializeSessionCookies()}\r
+ * @param bool $usePublicSuffixList Controls using Public Suffix List,\r
+ * see {@link usePublicSuffixList()}\r
+ */\r
+ public function __construct(\r
+ $serializeSessionCookies = false, $usePublicSuffixList = true\r
+ ) {\r
$this->serializeSessionCookies($serializeSessionCookies);\r
$this->usePublicSuffixList($usePublicSuffixList);\r
}\r
\r
- /**\r
- * Returns current time formatted in ISO-8601 at UTC timezone\r
- *\r
- * @return string\r
- */\r
+ /**\r
+ * Returns current time formatted in ISO-8601 at UTC timezone\r
+ *\r
+ * @return string\r
+ */\r
protected function now()\r
{\r
$dt = new DateTime();\r
return $dt->format(DateTime::ISO8601);\r
}\r
\r
- /**\r
- * Checks cookie array for correctness, possibly updating its 'domain', 'path' and 'expires' fields\r
- *\r
- * The checks are as follows:\r
- * - cookie array should contain 'name' and 'value' fields;\r
- * - name and value should not contain disallowed symbols;\r
- * - 'expires' should be either empty parseable by DateTime;\r
- * - 'domain' and 'path' should be either not empty or an URL where\r
- * cookie was set should be provided.\r
- * - if $setter is provided, then document at that URL should be allowed\r
- * to set a cookie for that 'domain'. If $setter is not provided,\r
- * then no domain checks will be made.\r
- *\r
- * 'expires' field will be converted to ISO8601 format from COOKIE format,\r
- * 'domain' and 'path' will be set from setter URL if empty.\r
- *\r
- * @param array cookie data, as returned by {@link HTTP_Request2_Response::getCookies()}\r
- * @param Net_URL2 URL of the document that sent Set-Cookie header\r
- * @return array Updated cookie array\r
- * @throws HTTP_Request2_LogicException\r
- * @throws HTTP_Request2_MessageException\r
- */\r
+ /**\r
+ * Checks cookie array for correctness, possibly updating its 'domain', 'path' and 'expires' fields\r
+ *\r
+ * The checks are as follows:\r
+ * - cookie array should contain 'name' and 'value' fields;\r
+ * - name and value should not contain disallowed symbols;\r
+ * - 'expires' should be either empty parseable by DateTime;\r
+ * - 'domain' and 'path' should be either not empty or an URL where\r
+ * cookie was set should be provided.\r
+ * - if $setter is provided, then document at that URL should be allowed\r
+ * to set a cookie for that 'domain'. If $setter is not provided,\r
+ * then no domain checks will be made.\r
+ *\r
+ * 'expires' field will be converted to ISO8601 format from COOKIE format,\r
+ * 'domain' and 'path' will be set from setter URL if empty.\r
+ *\r
+ * @param array $cookie cookie data, as returned by\r
+ * {@link HTTP_Request2_Response::getCookies()}\r
+ * @param Net_URL2 $setter URL of the document that sent Set-Cookie header\r
+ *\r
+ * @return array Updated cookie array\r
+ * @throws HTTP_Request2_LogicException\r
+ * @throws HTTP_Request2_MessageException\r
+ */\r
protected function checkAndUpdateFields(array $cookie, Net_URL2 $setter = null)\r
{\r
if ($missing = array_diff(array('name', 'value'), array_keys($cookie))) {\r
return $cookie;\r
}\r
\r
- /**\r
- * Stores a cookie in the jar\r
- *\r
- * @param array cookie data, as returned by {@link HTTP_Request2_Response::getCookies()}\r
- * @param Net_URL2 URL of the document that sent Set-Cookie header\r
- * @throws HTTP_Request2_Exception\r
- */\r
+ /**\r
+ * Stores a cookie in the jar\r
+ *\r
+ * @param array $cookie cookie data, as returned by\r
+ * {@link HTTP_Request2_Response::getCookies()}\r
+ * @param Net_URL2 $setter URL of the document that sent Set-Cookie header\r
+ *\r
+ * @throws HTTP_Request2_Exception\r
+ */\r
public function store(array $cookie, Net_URL2 $setter = null)\r
{\r
$cookie = $this->checkAndUpdateFields($cookie, $setter);\r
}\r
}\r
\r
- /**\r
- * Adds cookies set in HTTP response to the jar\r
- *\r
- * @param HTTP_Request2_Response response\r
- * @param Net_URL2 original request URL, needed for setting\r
- * default domain/path\r
- */\r
+ /**\r
+ * Adds cookies set in HTTP response to the jar\r
+ *\r
+ * @param HTTP_Request2_Response $response HTTP response message\r
+ * @param Net_URL2 $setter original request URL, needed for\r
+ * setting default domain/path\r
+ */\r
public function addCookiesFromResponse(HTTP_Request2_Response $response, Net_URL2 $setter)\r
{\r
foreach ($response->getCookies() as $cookie) {\r
}\r
}\r
\r
- /**\r
- * Returns all cookies matching a given request URL\r
- *\r
- * The following checks are made:\r
- * - cookie domain should match request host\r
- * - cookie path should be a prefix for request path\r
- * - 'secure' cookies will only be sent for HTTPS requests\r
- *\r
- * @param Net_URL2\r
- * @param bool Whether to return cookies as string for "Cookie: " header\r
- * @return array\r
- */\r
+ /**\r
+ * Returns all cookies matching a given request URL\r
+ *\r
+ * The following checks are made:\r
+ * - cookie domain should match request host\r
+ * - cookie path should be a prefix for request path\r
+ * - 'secure' cookies will only be sent for HTTPS requests\r
+ *\r
+ * @param Net_URL2 $url Request url\r
+ * @param bool $asString Whether to return cookies as string for "Cookie: " header\r
+ *\r
+ * @return array|string Matching cookies\r
+ */\r
public function getMatching(Net_URL2 $url, $asString = false)\r
{\r
$host = $url->getHost();\r
}\r
}\r
\r
- /**\r
- * Returns all cookies stored in a jar\r
- *\r
- * @return array\r
- */\r
+ /**\r
+ * Returns all cookies stored in a jar\r
+ *\r
+ * @return array\r
+ */\r
public function getAll()\r
{\r
$cookies = array();\r
return $cookies;\r
}\r
\r
- /**\r
- * Sets whether session cookies should be serialized when serializing the jar\r
- *\r
- * @param boolean\r
- */\r
+ /**\r
+ * Sets whether session cookies should be serialized when serializing the jar\r
+ *\r
+ * @param boolean $serialize serialize?\r
+ */\r
public function serializeSessionCookies($serialize)\r
{\r
$this->serializeSession = (bool)$serialize;\r
}\r
\r
- /**\r
- * Sets whether Public Suffix List should be used for restricting cookie-setting\r
- *\r
- * Without PSL {@link domainMatch()} will only prevent setting cookies for\r
- * top-level domains like '.com' or '.org'. However, it will not prevent\r
- * setting a cookie for '.co.uk' even though only third-level registrations\r
- * are possible in .uk domain.\r
- *\r
- * With the List it is possible to find the highest level at which a domain\r
- * may be registered for a particular top-level domain and consequently\r
- * prevent cookies set for '.co.uk' or '.msk.ru'. The same list is used by\r
- * Firefox, Chrome and Opera browsers to restrict cookie setting.\r
- *\r
- * Note that PSL is licensed differently to HTTP_Request2 package (refer to\r
- * the license information in public-suffix-list.php), so you can disable\r
- * its use if this is an issue for you.\r
- *\r
- * @param boolean\r
- * @link http://publicsuffix.org/learn/\r
- */\r
+ /**\r
+ * Sets whether Public Suffix List should be used for restricting cookie-setting\r
+ *\r
+ * Without PSL {@link domainMatch()} will only prevent setting cookies for\r
+ * top-level domains like '.com' or '.org'. However, it will not prevent\r
+ * setting a cookie for '.co.uk' even though only third-level registrations\r
+ * are possible in .uk domain.\r
+ *\r
+ * With the List it is possible to find the highest level at which a domain\r
+ * may be registered for a particular top-level domain and consequently\r
+ * prevent cookies set for '.co.uk' or '.msk.ru'. The same list is used by\r
+ * Firefox, Chrome and Opera browsers to restrict cookie setting.\r
+ *\r
+ * Note that PSL is licensed differently to HTTP_Request2 package (refer to\r
+ * the license information in public-suffix-list.php), so you can disable\r
+ * its use if this is an issue for you.\r
+ *\r
+ * @param boolean $useList use the list?\r
+ *\r
+ * @link http://publicsuffix.org/learn/\r
+ */\r
public function usePublicSuffixList($useList)\r
{\r
$this->useList = (bool)$useList;\r
}\r
\r
- /**\r
- * Returns string representation of object\r
- *\r
- * @return string\r
- * @see Serializable::serialize()\r
- */\r
+ /**\r
+ * Returns string representation of object\r
+ *\r
+ * @return string\r
+ *\r
+ * @see Serializable::serialize()\r
+ */\r
public function serialize()\r
{\r
$cookies = $this->getAll();\r
));\r
}\r
\r
- /**\r
- * Constructs the object from serialized string\r
- *\r
- * @param string string representation\r
- * @see Serializable::unserialize()\r
- */\r
+ /**\r
+ * Constructs the object from serialized string\r
+ *\r
+ * @param string $serialized string representation\r
+ *\r
+ * @see Serializable::unserialize()\r
+ */\r
public function unserialize($serialized)\r
{\r
$data = unserialize($serialized);\r
}\r
}\r
\r
- /**\r
- * Checks whether a cookie domain matches a request host.\r
- *\r
- * The method is used by {@link store()} to check for whether a document\r
- * at given URL can set a cookie with a given domain attribute and by\r
- * {@link getMatching()} to find cookies matching the request URL.\r
- *\r
- * @param string request host\r
- * @param string cookie domain\r
- * @return bool match success\r
- */\r
+ /**\r
+ * Checks whether a cookie domain matches a request host.\r
+ *\r
+ * The method is used by {@link store()} to check for whether a document\r
+ * at given URL can set a cookie with a given domain attribute and by\r
+ * {@link getMatching()} to find cookies matching the request URL.\r
+ *\r
+ * @param string $requestHost request host\r
+ * @param string $cookieDomain cookie domain\r
+ *\r
+ * @return bool match success\r
+ */\r
public function domainMatch($requestHost, $cookieDomain)\r
{\r
if ($requestHost == $cookieDomain) {\r
return substr('.' . $requestHost, -strlen($cookieDomain)) == $cookieDomain;\r
}\r
\r
- /**\r
- * Removes subdomains to get the registered domain (the first after top-level)\r
- *\r
- * The method will check Public Suffix List to find out where top-level\r
- * domain ends and registered domain starts. It will remove domain parts\r
- * to the left of registered one.\r
- *\r
- * @param string domain name\r
- * @return string|bool registered domain, will return false if $domain is\r
- * either invalid or a TLD itself\r
- */\r
+ /**\r
+ * Removes subdomains to get the registered domain (the first after top-level)\r
+ *\r
+ * The method will check Public Suffix List to find out where top-level\r
+ * domain ends and registered domain starts. It will remove domain parts\r
+ * to the left of registered one.\r
+ *\r
+ * @param string $domain domain name\r
+ *\r
+ * @return string|bool registered domain, will return false if $domain is\r
+ * either invalid or a TLD itself\r
+ */\r
public static function getRegisteredDomain($domain)\r
{\r
$domainParts = explode('.', ltrim($domain, '.'));\r
if (empty(self::$psl)) {\r
$path = '@data_dir@' . DIRECTORY_SEPARATOR . 'HTTP_Request2';\r
if (0 === strpos($path, '@' . 'data_dir@')) {\r
- $path = realpath(dirname(__FILE__) . DIRECTORY_SEPARATOR . '..'\r
- . DIRECTORY_SEPARATOR . 'data');\r
+ $path = realpath(\r
+ dirname(__FILE__) . DIRECTORY_SEPARATOR . '..'\r
+ . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'data'\r
+ );\r
}\r
self::$psl = include_once $path . DIRECTORY_SEPARATOR . 'public-suffix-list.php';\r
}\r
return $result;\r
}\r
\r
- /**\r
- * Recursive helper method for {@link getRegisteredDomain()}\r
- *\r
- * @param array remaining domain parts\r
- * @param mixed node in {@link HTTP_Request2_CookieJar::$psl} to check\r
- * @return string|null concatenated domain parts, null in case of error\r
- */\r
+ /**\r
+ * Recursive helper method for {@link getRegisteredDomain()}\r
+ *\r
+ * @param array $domainParts remaining domain parts\r
+ * @param mixed $listNode node in {@link HTTP_Request2_CookieJar::$psl} to check\r
+ *\r
+ * @return string|null concatenated domain parts, null in case of error\r
+ */\r
protected static function checkDomainsList(array $domainParts, $listNode)\r
{\r
$sub = array_pop($domainParts);\r
\r
if (!is_array($listNode) || is_null($sub)\r
|| array_key_exists('!' . $sub, $listNode)\r
- ) {\r
+ ) {\r
return $sub;\r
\r
} elseif (array_key_exists($sub, $listNode)) {\r