3 * Zend Framework (http://framework.zend.com/)
5 * @see http://github.com/zendframework/zend-diactoros for the canonical source repository
6 * @copyright Copyright (c) 2015-2016 Zend Technologies USA Inc. (http://www.zend.com)
7 * @license https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
10 namespace Zend\Diactoros;
12 use InvalidArgumentException;
13 use Psr\Http\Message\StreamInterface;
16 * Trait implementing the various methods defined in MessageInterface.
18 * @see https://github.com/php-fig/http-message/tree/master/src/MessageInterface.php
23 * List of all registered headers, as key => array of values.
27 protected $headers = [];
30 * Map of normalized header name to original name used to register header.
34 protected $headerNames = [];
39 private $protocol = '1.1';
42 * @var StreamInterface
47 * Retrieves the HTTP protocol version as a string.
49 * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
51 * @return string HTTP protocol version.
53 public function getProtocolVersion()
55 return $this->protocol;
59 * Return an instance with the specified HTTP protocol version.
61 * The version string MUST contain only the HTTP version number (e.g.,
64 * This method MUST be implemented in such a way as to retain the
65 * immutability of the message, and MUST return an instance that has the
66 * new protocol version.
68 * @param string $version HTTP protocol version
71 public function withProtocolVersion($version)
73 $this->validateProtocolVersion($version);
75 $new->protocol = $version;
80 * Retrieves all message headers.
82 * The keys represent the header name as it will be sent over the wire, and
83 * each value is an array of strings associated with the header.
85 * // Represent the headers as a string
86 * foreach ($message->getHeaders() as $name => $values) {
87 * echo $name . ": " . implode(", ", $values);
90 * // Emit headers iteratively:
91 * foreach ($message->getHeaders() as $name => $values) {
92 * foreach ($values as $value) {
93 * header(sprintf('%s: %s', $name, $value), false);
97 * @return array Returns an associative array of the message's headers. Each
98 * key MUST be a header name, and each value MUST be an array of strings.
100 public function getHeaders()
102 return $this->headers;
106 * Checks if a header exists by the given case-insensitive name.
108 * @param string $header Case-insensitive header name.
109 * @return bool Returns true if any header names match the given header
110 * name using a case-insensitive string comparison. Returns false if
111 * no matching header name is found in the message.
113 public function hasHeader($header)
115 return isset($this->headerNames[strtolower($header)]);
119 * Retrieves a message header value by the given case-insensitive name.
121 * This method returns an array of all the header values of the given
122 * case-insensitive header name.
124 * If the header does not appear in the message, this method MUST return an
127 * @param string $header Case-insensitive header field name.
128 * @return string[] An array of string values as provided for the given
129 * header. If the header does not appear in the message, this method MUST
130 * return an empty array.
132 public function getHeader($header)
134 if (! $this->hasHeader($header)) {
138 $header = $this->headerNames[strtolower($header)];
140 return $this->headers[$header];
144 * Retrieves a comma-separated string of the values for a single header.
146 * This method returns all of the header values of the given
147 * case-insensitive header name as a string concatenated together using
150 * NOTE: Not all header values may be appropriately represented using
151 * comma concatenation. For such headers, use getHeader() instead
152 * and supply your own delimiter when concatenating.
154 * If the header does not appear in the message, this method MUST return
157 * @param string $name Case-insensitive header field name.
158 * @return string A string of values as provided for the given header
159 * concatenated together using a comma. If the header does not appear in
160 * the message, this method MUST return an empty string.
162 public function getHeaderLine($name)
164 $value = $this->getHeader($name);
169 return implode(',', $value);
173 * Return an instance with the provided header, replacing any existing
174 * values of any headers with the same case-insensitive name.
176 * While header names are case-insensitive, the casing of the header will
177 * be preserved by this function, and returned from getHeaders().
179 * This method MUST be implemented in such a way as to retain the
180 * immutability of the message, and MUST return an instance that has the
181 * new and/or updated header and value.
183 * @param string $header Case-insensitive header field name.
184 * @param string|string[] $value Header value(s).
186 * @throws \InvalidArgumentException for invalid header names or values.
188 public function withHeader($header, $value)
190 $this->assertHeader($header);
192 $normalized = strtolower($header);
195 if ($new->hasHeader($header)) {
196 unset($new->headers[$new->headerNames[$normalized]]);
199 $value = $this->filterHeaderValue($value);
201 $new->headerNames[$normalized] = $header;
202 $new->headers[$header] = $value;
208 * Return an instance with the specified header appended with the
211 * Existing values for the specified header will be maintained. The new
212 * value(s) will be appended to the existing list. If the header did not
213 * exist previously, it will be added.
215 * This method MUST be implemented in such a way as to retain the
216 * immutability of the message, and MUST return an instance that has the
217 * new header and/or value.
219 * @param string $header Case-insensitive header field name to add.
220 * @param string|string[] $value Header value(s).
222 * @throws \InvalidArgumentException for invalid header names or values.
224 public function withAddedHeader($header, $value)
226 $this->assertHeader($header);
228 if (! $this->hasHeader($header)) {
229 return $this->withHeader($header, $value);
232 $header = $this->headerNames[strtolower($header)];
235 $value = $this->filterHeaderValue($value);
236 $new->headers[$header] = array_merge($this->headers[$header], $value);
241 * Return an instance without the specified header.
243 * Header resolution MUST be done without case-sensitivity.
245 * This method MUST be implemented in such a way as to retain the
246 * immutability of the message, and MUST return an instance that removes
249 * @param string $header Case-insensitive header field name to remove.
252 public function withoutHeader($header)
254 if (! $this->hasHeader($header)) {
258 $normalized = strtolower($header);
259 $original = $this->headerNames[$normalized];
262 unset($new->headers[$original], $new->headerNames[$normalized]);
267 * Gets the body of the message.
269 * @return StreamInterface Returns the body as a stream.
271 public function getBody()
273 return $this->stream;
277 * Return an instance with the specified message body.
279 * The body MUST be a StreamInterface object.
281 * This method MUST be implemented in such a way as to retain the
282 * immutability of the message, and MUST return a new instance that has the
285 * @param StreamInterface $body Body.
287 * @throws \InvalidArgumentException When the body is not valid.
289 public function withBody(StreamInterface $body)
292 $new->stream = $body;
296 private function getStream($stream, $modeIfNotInstance)
298 if ($stream instanceof StreamInterface) {
302 if (! is_string($stream) && ! is_resource($stream)) {
303 throw new InvalidArgumentException(
304 'Stream must be a string stream resource identifier, '
305 . 'an actual stream resource, '
306 . 'or a Psr\Http\Message\StreamInterface implementation'
310 return new Stream($stream, $modeIfNotInstance);
314 * Filter a set of headers to ensure they are in the correct internal format.
316 * Used by message constructors to allow setting all initial headers at once.
318 * @param array $originalHeaders Headers to filter.
320 private function setHeaders(array $originalHeaders)
322 $headerNames = $headers = [];
324 foreach ($originalHeaders as $header => $value) {
325 $value = $this->filterHeaderValue($value);
327 $this->assertHeader($header);
329 $headerNames[strtolower($header)] = $header;
330 $headers[$header] = $value;
333 $this->headerNames = $headerNames;
334 $this->headers = $headers;
338 * Validate the HTTP protocol version
340 * @param string $version
341 * @throws InvalidArgumentException on invalid HTTP protocol version
343 private function validateProtocolVersion($version)
345 if (empty($version)) {
346 throw new InvalidArgumentException(sprintf(
347 'HTTP protocol version can not be empty'
350 if (! is_string($version)) {
351 throw new InvalidArgumentException(sprintf(
352 'Unsupported HTTP protocol version; must be a string, received %s',
353 (is_object($version) ? get_class($version) : gettype($version))
357 // HTTP/1 uses a "<major>.<minor>" numbering scheme to indicate
358 // versions of the protocol, while HTTP/2 does not.
359 if (! preg_match('#^(1\.[01]|2)$#', $version)) {
360 throw new InvalidArgumentException(sprintf(
361 'Unsupported HTTP protocol version "%s" provided',
368 * @param mixed $values
371 private function filterHeaderValue($values)
373 if (! is_array($values)) {
377 return array_map(function ($value) {
378 HeaderSecurity::assertValid($value);
380 return (string) $value;
385 * Ensure header name and values are valid.
387 * @param string $name
389 * @throws InvalidArgumentException
391 private function assertHeader($name)
393 HeaderSecurity::assertValidName($name);