3 * @see https://github.com/zendframework/zend-diactoros for the canonical source repository
4 * @copyright Copyright (c) 2015-2017 Zend Technologies USA Inc. (http://www.zend.com)
5 * @license https://github.com/zendframework/zend-diactoros/blob/master/LICENSE.md New BSD License
8 namespace Zend\Diactoros;
10 use InvalidArgumentException;
11 use Psr\Http\Message\StreamInterface;
14 * Trait implementing the various methods defined in MessageInterface.
16 * @see https://github.com/php-fig/http-message/tree/master/src/MessageInterface.php
21 * List of all registered headers, as key => array of values.
25 protected $headers = [];
28 * Map of normalized header name to original name used to register header.
32 protected $headerNames = [];
37 private $protocol = '1.1';
40 * @var StreamInterface
45 * Retrieves the HTTP protocol version as a string.
47 * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
49 * @return string HTTP protocol version.
51 public function getProtocolVersion()
53 return $this->protocol;
57 * Return an instance with the specified HTTP protocol version.
59 * The version string MUST contain only the HTTP version number (e.g.,
62 * This method MUST be implemented in such a way as to retain the
63 * immutability of the message, and MUST return an instance that has the
64 * new protocol version.
66 * @param string $version HTTP protocol version
69 public function withProtocolVersion($version)
71 $this->validateProtocolVersion($version);
73 $new->protocol = $version;
78 * Retrieves all message headers.
80 * The keys represent the header name as it will be sent over the wire, and
81 * each value is an array of strings associated with the header.
83 * // Represent the headers as a string
84 * foreach ($message->getHeaders() as $name => $values) {
85 * echo $name . ": " . implode(", ", $values);
88 * // Emit headers iteratively:
89 * foreach ($message->getHeaders() as $name => $values) {
90 * foreach ($values as $value) {
91 * header(sprintf('%s: %s', $name, $value), false);
95 * @return array Returns an associative array of the message's headers. Each
96 * key MUST be a header name, and each value MUST be an array of strings.
98 public function getHeaders()
100 return $this->headers;
104 * Checks if a header exists by the given case-insensitive name.
106 * @param string $header Case-insensitive header name.
107 * @return bool Returns true if any header names match the given header
108 * name using a case-insensitive string comparison. Returns false if
109 * no matching header name is found in the message.
111 public function hasHeader($header)
113 return isset($this->headerNames[strtolower($header)]);
117 * Retrieves a message header value by the given case-insensitive name.
119 * This method returns an array of all the header values of the given
120 * case-insensitive header name.
122 * If the header does not appear in the message, this method MUST return an
125 * @param string $header Case-insensitive header field name.
126 * @return string[] An array of string values as provided for the given
127 * header. If the header does not appear in the message, this method MUST
128 * return an empty array.
130 public function getHeader($header)
132 if (! $this->hasHeader($header)) {
136 $header = $this->headerNames[strtolower($header)];
138 return $this->headers[$header];
142 * Retrieves a comma-separated string of the values for a single header.
144 * This method returns all of the header values of the given
145 * case-insensitive header name as a string concatenated together using
148 * NOTE: Not all header values may be appropriately represented using
149 * comma concatenation. For such headers, use getHeader() instead
150 * and supply your own delimiter when concatenating.
152 * If the header does not appear in the message, this method MUST return
155 * @param string $name Case-insensitive header field name.
156 * @return string A string of values as provided for the given header
157 * concatenated together using a comma. If the header does not appear in
158 * the message, this method MUST return an empty string.
160 public function getHeaderLine($name)
162 $value = $this->getHeader($name);
167 return implode(',', $value);
171 * Return an instance with the provided header, replacing any existing
172 * values of any headers with the same case-insensitive name.
174 * While header names are case-insensitive, the casing of the header will
175 * be preserved by this function, and returned from getHeaders().
177 * This method MUST be implemented in such a way as to retain the
178 * immutability of the message, and MUST return an instance that has the
179 * new and/or updated header and value.
181 * @param string $header Case-insensitive header field name.
182 * @param string|string[] $value Header value(s).
184 * @throws \InvalidArgumentException for invalid header names or values.
186 public function withHeader($header, $value)
188 $this->assertHeader($header);
190 $normalized = strtolower($header);
193 if ($new->hasHeader($header)) {
194 unset($new->headers[$new->headerNames[$normalized]]);
197 $value = $this->filterHeaderValue($value);
199 $new->headerNames[$normalized] = $header;
200 $new->headers[$header] = $value;
206 * Return an instance with the specified header appended with the
209 * Existing values for the specified header will be maintained. The new
210 * value(s) will be appended to the existing list. If the header did not
211 * exist previously, it will be added.
213 * This method MUST be implemented in such a way as to retain the
214 * immutability of the message, and MUST return an instance that has the
215 * new header and/or value.
217 * @param string $header Case-insensitive header field name to add.
218 * @param string|string[] $value Header value(s).
220 * @throws \InvalidArgumentException for invalid header names or values.
222 public function withAddedHeader($header, $value)
224 $this->assertHeader($header);
226 if (! $this->hasHeader($header)) {
227 return $this->withHeader($header, $value);
230 $header = $this->headerNames[strtolower($header)];
233 $value = $this->filterHeaderValue($value);
234 $new->headers[$header] = array_merge($this->headers[$header], $value);
239 * Return an instance without the specified header.
241 * Header resolution MUST be done without case-sensitivity.
243 * This method MUST be implemented in such a way as to retain the
244 * immutability of the message, and MUST return an instance that removes
247 * @param string $header Case-insensitive header field name to remove.
250 public function withoutHeader($header)
252 if (! $this->hasHeader($header)) {
256 $normalized = strtolower($header);
257 $original = $this->headerNames[$normalized];
260 unset($new->headers[$original], $new->headerNames[$normalized]);
265 * Gets the body of the message.
267 * @return StreamInterface Returns the body as a stream.
269 public function getBody()
271 return $this->stream;
275 * Return an instance with the specified message body.
277 * The body MUST be a StreamInterface object.
279 * This method MUST be implemented in such a way as to retain the
280 * immutability of the message, and MUST return a new instance that has the
283 * @param StreamInterface $body Body.
285 * @throws \InvalidArgumentException When the body is not valid.
287 public function withBody(StreamInterface $body)
290 $new->stream = $body;
294 private function getStream($stream, $modeIfNotInstance)
296 if ($stream instanceof StreamInterface) {
300 if (! is_string($stream) && ! is_resource($stream)) {
301 throw new InvalidArgumentException(
302 'Stream must be a string stream resource identifier, '
303 . 'an actual stream resource, '
304 . 'or a Psr\Http\Message\StreamInterface implementation'
308 return new Stream($stream, $modeIfNotInstance);
312 * Filter a set of headers to ensure they are in the correct internal format.
314 * Used by message constructors to allow setting all initial headers at once.
316 * @param array $originalHeaders Headers to filter.
318 private function setHeaders(array $originalHeaders)
320 $headerNames = $headers = [];
322 foreach ($originalHeaders as $header => $value) {
323 $value = $this->filterHeaderValue($value);
325 $this->assertHeader($header);
327 $headerNames[strtolower($header)] = $header;
328 $headers[$header] = $value;
331 $this->headerNames = $headerNames;
332 $this->headers = $headers;
336 * Validate the HTTP protocol version
338 * @param string $version
339 * @throws InvalidArgumentException on invalid HTTP protocol version
341 private function validateProtocolVersion($version)
343 if (empty($version)) {
344 throw new InvalidArgumentException(
345 'HTTP protocol version can not be empty'
348 if (! is_string($version)) {
349 throw new InvalidArgumentException(sprintf(
350 'Unsupported HTTP protocol version; must be a string, received %s',
351 (is_object($version) ? get_class($version) : gettype($version))
355 // HTTP/1 uses a "<major>.<minor>" numbering scheme to indicate
356 // versions of the protocol, while HTTP/2 does not.
357 if (! preg_match('#^(1\.[01]|2)$#', $version)) {
358 throw new InvalidArgumentException(sprintf(
359 'Unsupported HTTP protocol version "%s" provided',
366 * @param mixed $values
369 private function filterHeaderValue($values)
371 if (! is_array($values)) {
375 return array_map(function ($value) {
376 HeaderSecurity::assertValid($value);
378 return (string) $value;
383 * Ensure header name and values are valid.
385 * @param string $name
387 * @throws InvalidArgumentException
389 private function assertHeader($name)
391 HeaderSecurity::assertValidName($name);