HeaderCollection.php 6.89 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
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
24
class HeaderCollection extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
Qiang Xue committed
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
    /**
     * @var array the headers in this collection (indexed by the header names)
     */
    private $_headers = [];

    /**
     * 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).
64 65 66 67
     * @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.
68
     * @return string|array the named header(s). If `$first` is true, a string will be returned;
69
     * If `$first` is false, an array will be returned.
70 71 72 73 74 75 76 77 78 79 80 81 82 83
     */
    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.
84 85
     * @param string $name the name of the header
     * @param string $value the value of the header
86 87 88 89 90 91 92 93 94 95 96 97 98 99
     * @return static the collection object itself
     */
    public function set($name, $value = '')
    {
        $name = strtolower($name);
        $this->_headers[$name] = (array) $value;

        return $this;
    }

    /**
     * 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.
100 101
     * @param string $name the name of the header
     * @param string $value the value of the header
102 103 104 105 106 107 108 109 110 111 112 113 114
     * @return static the collection object itself
     */
    public function add($name, $value)
    {
        $name = strtolower($name);
        $this->_headers[$name][] = $value;

        return $this;
    }

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

        return $this;
    }

    /**
     * Returns a value indicating whether the named header exists.
131
     * @param string $name the name of the header
132 133 134 135 136 137 138 139 140 141 142
     * @return boolean whether the named header exists
     */
    public function has($name)
    {
        $name = strtolower($name);

        return isset($this->_headers[$name]);
    }

    /**
     * Removes a header.
143
     * @param string $name the name of the header to be removed.
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
     * @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 = [];
    }

    /**
     * Returns the collection as a PHP array.
     * @return array the array representation of the collection.
170
     * The array keys are header names, and the array values are the corresponding header values.
171 172 173 174 175 176 177 178 179 180
     */
    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])`.
181
     * @param string $name the header name
182 183 184 185 186 187 188 189 190 191 192 193
     * @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()]].
194
     * @param string $name the header name
195 196 197 198 199 200 201 202 203 204 205 206
     * @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()]].
207
     * @param string $name the header name
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
     * @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);
    }
Qiang Xue committed
226
}