CookieCollection.php 6.55 KB
Newer Older
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
Qiang Xue committed
5 6 7 8 9
 * @license http://www.yiiframework.com/license/
 */

namespace yii\web;

Qiang Xue committed
10
use Yii;
11
use ArrayIterator;
12
use yii\base\Arrayable;
Qiang Xue committed
13 14
use yii\base\InvalidCallException;
use yii\base\Object;
Qiang Xue committed
15 16

/**
17
 * CookieCollection maintains the cookies available in the current request.
Qiang Xue committed
18
 *
19 20 21
 * @property integer $count The number of cookies in the collection. This property is read-only.
 * @property ArrayIterator $iterator An iterator for traversing the cookies in the collection. This property
 * is read-only.
Qiang Xue committed
22 23 24 25
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
26
class CookieCollection extends Object implements \IteratorAggregate, \ArrayAccess, \Countable, Arrayable
Qiang Xue committed
27
{
Qiang Xue committed
28
	/**
Qiang Xue committed
29
	 * @var boolean whether this collection is read only.
Qiang Xue committed
30
	 */
Qiang Xue committed
31
	public $readOnly = false;
Qiang Xue committed
32

Qiang Xue committed
33
	/**
34
	 * @var Cookie[] the cookies in this collection (indexed by the cookie names)
Qiang Xue committed
35
	 */
Alexander Makarov committed
36
	private $_cookies = [];
Qiang Xue committed
37 38 39

	/**
	 * Constructor.
Qiang Xue committed
40 41
	 * @param array $cookies the cookies that this collection initially contains. This should be
	 * an array of name-value pairs.s
Qiang Xue committed
42 43
	 * @param array $config name-value pairs that will be used to initialize the object properties
	 */
Alexander Makarov committed
44
	public function __construct($cookies = [], $config = [])
Qiang Xue committed
45
	{
Qiang Xue committed
46
		$this->_cookies = $cookies;
Qiang Xue committed
47 48 49 50
		parent::__construct($config);
	}

	/**
51
	 * Returns an iterator for traversing the cookies in the collection.
Qiang Xue committed
52
	 * This method is required by the SPL interface `IteratorAggregate`.
53
	 * It will be implicitly called when you use `foreach` to traverse the collection.
54
	 * @return ArrayIterator an iterator for traversing the cookies in the collection.
Qiang Xue committed
55 56 57
	 */
	public function getIterator()
	{
58
		return new ArrayIterator($this->_cookies);
Qiang Xue committed
59 60 61
	}

	/**
62
	 * Returns the number of cookies in the collection.
Qiang Xue committed
63
	 * This method is required by the SPL `Countable` interface.
64 65
	 * It will be implicitly called when you use `count($collection)`.
	 * @return integer the number of cookies in the collection.
Qiang Xue committed
66 67 68 69 70 71 72
	 */
	public function count()
	{
		return $this->getCount();
	}

	/**
73 74
	 * Returns the number of cookies in the collection.
	 * @return integer the number of cookies in the collection.
Qiang Xue committed
75 76 77 78 79 80 81
	 */
	public function getCount()
	{
		return count($this->_cookies);
	}

	/**
82 83 84 85
	 * Returns the cookie with the specified name.
	 * @param string $name the cookie name
	 * @return Cookie the cookie with the specified name. Null if the named cookie does not exist.
	 * @see getValue()
Qiang Xue committed
86
	 */
87
	public function get($name)
Qiang Xue committed
88
	{
89
		return isset($this->_cookies[$name]) ? $this->_cookies[$name] : null;
Qiang Xue committed
90 91 92
	}

	/**
93 94 95 96 97
	 * Returns the value of the named cookie.
	 * @param string $name the cookie name
	 * @param mixed $defaultValue the value that should be returned when the named cookie does not exist.
	 * @return mixed the value of the named cookie.
	 * @see get()
Qiang Xue committed
98
	 */
Qiang Xue committed
99
	public function getValue($name, $defaultValue = null)
Qiang Xue committed
100
	{
101
		return isset($this->_cookies[$name]) ? $this->_cookies[$name]->value : $defaultValue;
Qiang Xue committed
102 103
	}

Qiang Xue committed
104 105 106 107 108 109 110 111 112 113
	/**
	 * Returns whether there is a cookie with the specified name.
	 * @param string $name the cookie name
	 * @return boolean whether the named cookie exists
	 */
	public function has($name)
	{
		return isset($this->_cookies[$name]);
	}

Qiang Xue committed
114
	/**
115 116 117
	 * Adds a cookie to the collection.
	 * If there is already a cookie with the same name in the collection, it will be removed first.
	 * @param Cookie $cookie the cookie to be added
Qiang Xue committed
118
	 * @throws InvalidCallException if the cookie collection is read only
Qiang Xue committed
119
	 */
120
	public function add($cookie)
Qiang Xue committed
121
	{
Qiang Xue committed
122 123
		if ($this->readOnly) {
			throw new InvalidCallException('The cookie collection is read only.');
Qiang Xue committed
124
		}
Qiang Xue committed
125 126 127 128
		$this->_cookies[$cookie->name] = $cookie;
	}

	/**
Qiang Xue committed
129 130 131
	 * Removes a cookie.
	 * If `$removeFromBrowser` is true, the cookie will be removed from the browser.
	 * In this case, a cookie with outdated expiry will be added to the collection.
132
	 * @param Cookie|string $cookie the cookie object or the name of the cookie to be removed.
Qiang Xue committed
133 134
	 * @param boolean $removeFromBrowser whether to remove the cookie from browser
	 * @throws InvalidCallException if the cookie collection is read only
Qiang Xue committed
135
	 */
Qiang Xue committed
136
	public function remove($cookie, $removeFromBrowser = true)
Qiang Xue committed
137
	{
Qiang Xue committed
138 139
		if ($this->readOnly) {
			throw new InvalidCallException('The cookie collection is read only.');
140 141
		}
		if ($cookie instanceof Cookie) {
Qiang Xue committed
142 143 144
			$cookie->expire = 1;
			$cookie->value = '';
		} else {
Alexander Makarov committed
145
			$cookie = new Cookie([
Qiang Xue committed
146 147
				'name' => $cookie,
				'expire' => 1,
Alexander Makarov committed
148
			]);
Qiang Xue committed
149 150 151 152
		}
		if ($removeFromBrowser) {
			$this->_cookies[$cookie->name] = $cookie;
		} else {
153 154
			unset($this->_cookies[$cookie->name]);
		}
Qiang Xue committed
155 156 157
	}

	/**
158
	 * Removes all cookies.
Qiang Xue committed
159
	 * @throws InvalidCallException if the cookie collection is read only
Qiang Xue committed
160
	 */
161
	public function removeAll()
Qiang Xue committed
162
	{
Qiang Xue committed
163 164
		if ($this->readOnly) {
			throw new InvalidCallException('The cookie collection is read only.');
Qiang Xue committed
165
		}
Alexander Makarov committed
166
		$this->_cookies = [];
Qiang Xue committed
167 168 169
	}

	/**
170 171 172 173
	 * Returns the collection as a PHP array.
	 * @return array the array representation of the collection.
	 * The array keys are cookie names, and the array values are the corresponding
	 * cookie objects.
Qiang Xue committed
174 175 176 177 178 179 180
	 */
	public function toArray()
	{
		return $this->_cookies;
	}

	/**
181
	 * Returns whether there is a cookie with the specified name.
Qiang Xue committed
182
	 * This method is required by the SPL interface `ArrayAccess`.
183 184 185
	 * It is implicitly called when you use something like `isset($collection[$name])`.
	 * @param string $name the cookie name
	 * @return boolean whether the named cookie exists
Qiang Xue committed
186
	 */
187
	public function offsetExists($name)
Qiang Xue committed
188
	{
Qiang Xue committed
189
		return $this->has($name);
Qiang Xue committed
190 191 192
	}

	/**
193
	 * Returns the cookie with the specified name.
Qiang Xue committed
194
	 * This method is required by the SPL interface `ArrayAccess`.
195 196 197 198
	 * It is implicitly called when you use something like `$cookie = $collection[$name];`.
	 * This is equivalent to [[get()]].
	 * @param string $name the cookie name
	 * @return Cookie the cookie with the specified name, null if the named cookie does not exist.
Qiang Xue committed
199
	 */
200
	public function offsetGet($name)
Qiang Xue committed
201
	{
202
		return $this->get($name);
Qiang Xue committed
203 204 205
	}

	/**
206
	 * Adds the cookie to the collection.
Qiang Xue committed
207
	 * This method is required by the SPL interface `ArrayAccess`.
208 209 210 211
	 * It is implicitly called when you use something like `$collection[$name] = $cookie;`.
	 * This is equivalent to [[add()]].
	 * @param string $name the cookie name
	 * @param Cookie $cookie the cookie to be added
Qiang Xue committed
212
	 */
213
	public function offsetSet($name, $cookie)
Qiang Xue committed
214
	{
215
		$this->add($cookie);
Qiang Xue committed
216 217 218
	}

	/**
219
	 * Removes the named cookie.
Qiang Xue committed
220
	 * This method is required by the SPL interface `ArrayAccess`.
221 222 223
	 * It is implicitly called when you use something like `unset($collection[$name])`.
	 * This is equivalent to [[remove()]].
	 * @param string $name the cookie name
Qiang Xue committed
224
	 */
225
	public function offsetUnset($name)
Qiang Xue committed
226
	{
227
		$this->remove($name);
Qiang Xue committed
228 229
	}
}