HeaderCollection.php 6.27 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\web;

use Yii;
use yii\base\Object;
use ArrayIterator;

/**
 * HeaderCollection is used by [[Response]] to maintain the currently registered HTTP headers.
 *
17 18 19
 * @property integer $count The number of headers in the collection. This property is read-only.
 * @property ArrayIterator $iterator An iterator for traversing the headers in the collection. This property
 * is read-only.
20
 *
Qiang Xue committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class HeaderCollection extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
{
	/**
	 * @var array the headers in this collection (indexed by the header names)
	 */
	private $_headers = array();

	/**
	 * Returns an iterator for traversing the headers in the collection.
	 * This method is required by the SPL interface `IteratorAggregate`.
	 * It will be implicitly called when you use `foreach` to traverse the collection.
	 * @return ArrayIterator an iterator for traversing the headers in the collection.
	 */
	public function getIterator()
	{
		return new ArrayIterator($this->_headers);
	}

	/**
	 * Returns the number of headers in the collection.
	 * This method is required by the SPL `Countable` interface.
	 * It will be implicitly called when you use `count($collection)`.
	 * @return integer the number of headers in the collection.
	 */
	public function count()
	{
		return $this->getCount();
	}

	/**
	 * Returns the number of headers in the collection.
	 * @return integer the number of headers in the collection.
	 */
	public function getCount()
	{
		return count($this->_headers);
	}

	/**
	 * Returns the named header(s).
	 * @param string $name the name of the header to return
	 * @param mixed $default the value to return in case the named header does not exist
	 * @param boolean $first whether to only return the first header of the specified name.
	 * If false, all headers of the specified name will be returned.
	 * @return string|array the named header(s). If `$first` is true, a string will be returned;
	 * If `$first` is false, an array will be returned.
	 */
	public function get($name, $default = null, $first = true)
	{
		$name = strtolower($name);
		if (isset($this->_headers[$name])) {
			return $first ? reset($this->_headers[$name]) : $this->_headers[$name];
		} else {
			return $default;
		}
	}

	/**
	 * Adds a new header.
	 * If there is already a header with the same name, it will be replaced.
	 * @param string $name the name of the header
	 * @param string $value the value of the header
Qiang Xue committed
86
	 * @return HeaderCollection the collection object itself
Qiang Xue committed
87
	 */
Qiang Xue committed
88
	public function set($name, $value = '')
Qiang Xue committed
89 90 91
	{
		$name = strtolower($name);
		$this->_headers[$name] = (array)$value;
Qiang Xue committed
92
		return $this;
Qiang Xue committed
93 94 95 96 97 98 99 100
	}

	/**
	 * Adds a new header.
	 * If there is already a header with the same name, the new one will
	 * be appended to it instead of replacing it.
	 * @param string $name the name of the header
	 * @param string $value the value of the header
Qiang Xue committed
101
	 * @return HeaderCollection the collection object itself
Qiang Xue committed
102 103 104 105 106
	 */
	public function add($name, $value)
	{
		$name = strtolower($name);
		$this->_headers[$name][] = $value;
Qiang Xue committed
107
		return $this;
Qiang Xue committed
108 109
	}

110
	/**
111
	 * Sets a new header only if it does not exist yet.
112 113 114 115 116
	 * If there is already a header with the same name, the new one will be ignored.
	 * @param string $name the name of the header
	 * @param string $value the value of the header
	 * @return HeaderCollection the collection object itself
	 */
117
	public function setDefault($name, $value)
118 119 120 121 122 123 124 125
	{
		$name = strtolower($name);
		if (empty($this->_headers[$name])) {
			$this->_headers[$name][] = $value;
		}
		return $this;
	}

Qiang Xue committed
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
	/**
	 * Returns a value indicating whether the named header exists.
	 * @param string $name the name of the header
	 * @return boolean whether the named header exists
	 */
	public function has($name)
	{
		$name = strtolower($name);
		return isset($this->_headers[$name]);
	}

	/**
	 * Removes a header.
	 * @param string $name the name of the header to be removed.
	 * @return string the value of the removed header. Null is returned if the header does not exist.
	 */
	public function remove($name)
	{
		$name = strtolower($name);
		if (isset($this->_headers[$name])) {
			$value = $this->_headers[$name];
			unset($this->_headers[$name]);
			return $value;
		} else {
			return null;
		}
	}

	/**
	 * Removes all headers.
	 */
	public function removeAll()
	{
		$this->_headers = array();
	}

	/**
	 * Returns the collection as a PHP array.
	 * @return array the array representation of the collection.
	 * The array keys are header names, and the array values are the corresponding header values.
	 */
	public function toArray()
	{
		return $this->_headers;
	}

	/**
	 * Returns whether there is a header with the specified name.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `isset($collection[$name])`.
	 * @param string $name the header name
	 * @return boolean whether the named header exists
	 */
	public function offsetExists($name)
	{
		return $this->has($name);
	}

	/**
	 * Returns the header with the specified name.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `$header = $collection[$name];`.
	 * This is equivalent to [[get()]].
	 * @param string $name the header name
	 * @return string the header value with the specified name, null if the named header does not exist.
	 */
	public function offsetGet($name)
	{
		return $this->get($name);
	}

	/**
	 * Adds the header to the collection.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `$collection[$name] = $header;`.
	 * This is equivalent to [[add()]].
	 * @param string $name the header name
	 * @param string $value the header value to be added
	 */
	public function offsetSet($name, $value)
	{
		$this->set($name, $value);
	}

	/**
	 * Removes the named header.
	 * This method is required by the SPL interface `ArrayAccess`.
	 * It is implicitly called when you use something like `unset($collection[$name])`.
	 * This is equivalent to [[remove()]].
	 * @param string $name the header name
	 */
	public function offsetUnset($name)
	{
		$this->remove($name);
	}
}