242 lines
7.7KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\web;
  8. use Yii;
  9. use ArrayIterator;
  10. use yii\base\InvalidCallException;
  11. use yii\base\Object;
  12. /**
  13. * CookieCollection maintains the cookies available in the current request.
  14. *
  15. * @property integer $count The number of cookies in the collection. This property is read-only.
  16. * @property ArrayIterator $iterator An iterator for traversing the cookies in the collection. This property
  17. * is read-only.
  18. *
  19. * @author Qiang Xue <qiang.xue@gmail.com>
  20. * @since 2.0
  21. */
  22. class CookieCollection extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
  23. {
  24. /**
  25. * @var boolean whether this collection is read only.
  26. */
  27. public $readOnly = false;
  28. /**
  29. * @var Cookie[] the cookies in this collection (indexed by the cookie names)
  30. */
  31. private $_cookies = [];
  32. /**
  33. * Constructor.
  34. * @param array $cookies the cookies that this collection initially contains. This should be
  35. * an array of name-value pairs.
  36. * @param array $config name-value pairs that will be used to initialize the object properties
  37. */
  38. public function __construct($cookies = [], $config = [])
  39. {
  40. $this->_cookies = $cookies;
  41. parent::__construct($config);
  42. }
  43. /**
  44. * Returns an iterator for traversing the cookies in the collection.
  45. * This method is required by the SPL interface [[\IteratorAggregate]].
  46. * It will be implicitly called when you use `foreach` to traverse the collection.
  47. * @return ArrayIterator an iterator for traversing the cookies in the collection.
  48. */
  49. public function getIterator()
  50. {
  51. return new ArrayIterator($this->_cookies);
  52. }
  53. /**
  54. * Returns the number of cookies in the collection.
  55. * This method is required by the SPL `Countable` interface.
  56. * It will be implicitly called when you use `count($collection)`.
  57. * @return integer the number of cookies in the collection.
  58. */
  59. public function count()
  60. {
  61. return $this->getCount();
  62. }
  63. /**
  64. * Returns the number of cookies in the collection.
  65. * @return integer the number of cookies in the collection.
  66. */
  67. public function getCount()
  68. {
  69. return count($this->_cookies);
  70. }
  71. /**
  72. * Returns the cookie with the specified name.
  73. * @param string $name the cookie name
  74. * @return Cookie the cookie with the specified name. Null if the named cookie does not exist.
  75. * @see getValue()
  76. */
  77. public function get($name)
  78. {
  79. return isset($this->_cookies[$name]) ? $this->_cookies[$name] : null;
  80. }
  81. /**
  82. * Returns the value of the named cookie.
  83. * @param string $name the cookie name
  84. * @param mixed $defaultValue the value that should be returned when the named cookie does not exist.
  85. * @return mixed the value of the named cookie.
  86. * @see get()
  87. */
  88. public function getValue($name, $defaultValue = null)
  89. {
  90. return isset($this->_cookies[$name]) ? $this->_cookies[$name]->value : $defaultValue;
  91. }
  92. /**
  93. * Returns whether there is a cookie with the specified name.
  94. * Note that if a cookie is marked for deletion from browser, this method will return false.
  95. * @param string $name the cookie name
  96. * @return boolean whether the named cookie exists
  97. * @see remove()
  98. */
  99. public function has($name)
  100. {
  101. return isset($this->_cookies[$name]) && $this->_cookies[$name]->value !== ''
  102. && ($this->_cookies[$name]->expire === null || $this->_cookies[$name]->expire >= time());
  103. }
  104. /**
  105. * Adds a cookie to the collection.
  106. * If there is already a cookie with the same name in the collection, it will be removed first.
  107. * @param Cookie $cookie the cookie to be added
  108. * @throws InvalidCallException if the cookie collection is read only
  109. */
  110. public function add($cookie)
  111. {
  112. if ($this->readOnly) {
  113. throw new InvalidCallException('The cookie collection is read only.');
  114. }
  115. $this->_cookies[$cookie->name] = $cookie;
  116. }
  117. /**
  118. * Removes a cookie.
  119. * If `$removeFromBrowser` is true, the cookie will be removed from the browser.
  120. * In this case, a cookie with outdated expiry will be added to the collection.
  121. * @param Cookie|string $cookie the cookie object or the name of the cookie to be removed.
  122. * @param boolean $removeFromBrowser whether to remove the cookie from browser
  123. * @throws InvalidCallException if the cookie collection is read only
  124. */
  125. public function remove($cookie, $removeFromBrowser = true)
  126. {
  127. if ($this->readOnly) {
  128. throw new InvalidCallException('The cookie collection is read only.');
  129. }
  130. if ($cookie instanceof Cookie) {
  131. $cookie->expire = 1;
  132. $cookie->value = '';
  133. } else {
  134. $cookie = new Cookie([
  135. 'name' => $cookie,
  136. 'expire' => 1,
  137. ]);
  138. }
  139. if ($removeFromBrowser) {
  140. $this->_cookies[$cookie->name] = $cookie;
  141. } else {
  142. unset($this->_cookies[$cookie->name]);
  143. }
  144. }
  145. /**
  146. * Removes all cookies.
  147. * @throws InvalidCallException if the cookie collection is read only
  148. */
  149. public function removeAll()
  150. {
  151. if ($this->readOnly) {
  152. throw new InvalidCallException('The cookie collection is read only.');
  153. }
  154. $this->_cookies = [];
  155. }
  156. /**
  157. * Returns the collection as a PHP array.
  158. * @return array the array representation of the collection.
  159. * The array keys are cookie names, and the array values are the corresponding cookie objects.
  160. */
  161. public function toArray()
  162. {
  163. return $this->_cookies;
  164. }
  165. /**
  166. * Populates the cookie collection from an array.
  167. * @param array $array the cookies to populate from
  168. * @since 2.0.3
  169. */
  170. public function fromArray(array $array)
  171. {
  172. $this->_cookies = $array;
  173. }
  174. /**
  175. * Returns whether there is a cookie with the specified name.
  176. * This method is required by the SPL interface [[\ArrayAccess]].
  177. * It is implicitly called when you use something like `isset($collection[$name])`.
  178. * @param string $name the cookie name
  179. * @return boolean whether the named cookie exists
  180. */
  181. public function offsetExists($name)
  182. {
  183. return $this->has($name);
  184. }
  185. /**
  186. * Returns the cookie with the specified name.
  187. * This method is required by the SPL interface [[\ArrayAccess]].
  188. * It is implicitly called when you use something like `$cookie = $collection[$name];`.
  189. * This is equivalent to [[get()]].
  190. * @param string $name the cookie name
  191. * @return Cookie the cookie with the specified name, null if the named cookie does not exist.
  192. */
  193. public function offsetGet($name)
  194. {
  195. return $this->get($name);
  196. }
  197. /**
  198. * Adds the cookie to the collection.
  199. * This method is required by the SPL interface [[\ArrayAccess]].
  200. * It is implicitly called when you use something like `$collection[$name] = $cookie;`.
  201. * This is equivalent to [[add()]].
  202. * @param string $name the cookie name
  203. * @param Cookie $cookie the cookie to be added
  204. */
  205. public function offsetSet($name, $cookie)
  206. {
  207. $this->add($cookie);
  208. }
  209. /**
  210. * Removes the named cookie.
  211. * This method is required by the SPL interface [[\ArrayAccess]].
  212. * It is implicitly called when you use something like `unset($collection[$name])`.
  213. * This is equivalent to [[remove()]].
  214. * @param string $name the cookie name
  215. */
  216. public function offsetUnset($name)
  217. {
  218. $this->remove($name);
  219. }
  220. }