ci4

1
<?php
2

3
declare(strict_types=1);
4

5
/**
6
 * This file is part of CodeIgniter 4 framework.
7
 *
8
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
9
 *
10
 * For the full copyright and license information, please view
11
 * the LICENSE file that was distributed with this source code.
12
 */
13

14
namespace CodeIgniter\HTTP;
15

16
use Stringable;
17

18
/**
19
 * Class Header
20
 *
21
 * Represents a single HTTP header.
22
 *
23
 * @see \CodeIgniter\HTTP\HeaderTest
24
 */
25
class Header implements Stringable
26
{
27
    /**
28
     * The name of the header.
29
     *
30
     * @var string
31
     */
32
    protected $name;
33

34
    /**
35
     * The value of the header. May have more than one
36
     * value. If so, will be an array of strings.
37
     * E.g.,
38
     *   [
39
     *       'foo',
40
     *       [
41
     *           'bar' => 'fizz',
42
     *       ],
43
     *       'baz' => 'buzz',
44
     *   ]
45
     *
46
     * @var array<int|string, array<string, string>|string>|string
47
     */
48
    protected $value;
49

50
    /**
51
     * Header constructor. name is mandatory, if a value is provided, it will be set.
52
     *
53
     * @param array<int|string, array<string, string>|string>|string|null $value
54
     */
55
    public function __construct(string $name, $value = null)
56
    {
57
        $this->name = $name;
58
        $this->setValue($value);
59
    }
60

61
    /**
62
     * Returns the name of the header, in the same case it was set.
63
     */
64
    public function getName(): string
65
    {
66
        return $this->name;
67
    }
68

69
    /**
70
     * Gets the raw value of the header. This may return either a string
71
     * or an array, depending on whether the header has multiple values or not.
72
     *
73
     * @return array<int|string, array<string, string>|string>|string
74
     */
75
    public function getValue()
76
    {
77
        return $this->value;
78
    }
79

80
    /**
81
     * Sets the name of the header, overwriting any previous value.
82
     *
83
     * @return $this
84
     */
85
    public function setName(string $name)
86
    {
87
        $this->name = $name;
88

89
        return $this;
90
    }
91

92
    /**
93
     * Sets the value of the header, overwriting any previous value(s).
94
     *
95
     * @param array<int|string, array<string, string>|string>|string|null $value
96
     *
97
     * @return $this
98
     */
99
    public function setValue($value = null)
100
    {
101
        $this->value = is_array($value) ? $value : (string) $value;
102

103
        return $this;
104
    }
105

106
    /**
107
     * Appends a value to the list of values for this header. If the
108
     * header is a single value string, it will be converted to an array.
109
     *
110
     * @param array<string, string>|string|null $value
111
     *
112
     * @return $this
113
     */
114
    public function appendValue($value = null)
115
    {
116
        if ($value === null) {
117
            return $this;
118
        }
119

120
        if (! is_array($this->value)) {
121
            $this->value = [$this->value];
122
        }
123

124
        if (! in_array($value, $this->value, true)) {
125
            $this->value[] = is_array($value) ? $value : (string) $value;
126
        }
127

128
        return $this;
129
    }
130

131
    /**
132
     * Prepends a value to the list of values for this header. If the
133
     * header is a single value string, it will be converted to an array.
134
     *
135
     * @param array<string, string>|string|null $value
136
     *
137
     * @return $this
138
     */
139
    public function prependValue($value = null)
140
    {
141
        if ($value === null) {
142
            return $this;
143
        }
144

145
        if (! is_array($this->value)) {
146
            $this->value = [$this->value];
147
        }
148

149
        array_unshift($this->value, $value);
150

151
        return $this;
152
    }
153

154
    /**
155
     * Retrieves a comma-separated string of the values for a single header.
156
     *
157
     * NOTE: Not all header values may be appropriately represented using
158
     * comma concatenation. For such headers, use getHeader() instead
159
     * and supply your own delimiter when concatenating.
160
     *
161
     * @see https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2
162
     */
163
    public function getValueLine(): string
164
    {
165
        if (is_string($this->value)) {
166
            return $this->value;
167
        }
168
        if (! is_array($this->value)) {
169
            return '';
170
        }
171

172
        $options = [];
173

174
        foreach ($this->value as $key => $value) {
175
            if (is_string($key) && ! is_array($value)) {
176
                $options[] = $key . '=' . $value;
177
            } elseif (is_array($value)) {
178
                $key       = key($value);
179
                $options[] = $key . '=' . $value[$key];
180
            } elseif (is_numeric($key)) {
181
                $options[] = $value;
182
            }
183
        }
184

185
        return implode(', ', $options);
186
    }
187

188
    /**
189
     * Returns a representation of the entire header string, including
190
     * the header name and all values converted to the proper format.
191
     */
192
    public function __toString(): string
193
    {
194
        return $this->name . ': ' . $this->getValueLine();
195
    }
196
}
197