annotate vendor/psr/http-message/src/MessageInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Psr\Http\Message;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * HTTP messages consist of requests from a client to a server and responses
Chris@0 7 * from a server to a client. This interface defines the methods common to
Chris@0 8 * each.
Chris@0 9 *
Chris@0 10 * Messages are considered immutable; all methods that might change state MUST
Chris@0 11 * be implemented such that they retain the internal state of the current
Chris@0 12 * message and return an instance that contains the changed state.
Chris@0 13 *
Chris@0 14 * @link http://www.ietf.org/rfc/rfc7230.txt
Chris@0 15 * @link http://www.ietf.org/rfc/rfc7231.txt
Chris@0 16 */
Chris@0 17 interface MessageInterface
Chris@0 18 {
Chris@0 19 /**
Chris@0 20 * Retrieves the HTTP protocol version as a string.
Chris@0 21 *
Chris@0 22 * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
Chris@0 23 *
Chris@0 24 * @return string HTTP protocol version.
Chris@0 25 */
Chris@0 26 public function getProtocolVersion();
Chris@0 27
Chris@0 28 /**
Chris@0 29 * Return an instance with the specified HTTP protocol version.
Chris@0 30 *
Chris@0 31 * The version string MUST contain only the HTTP version number (e.g.,
Chris@0 32 * "1.1", "1.0").
Chris@0 33 *
Chris@0 34 * This method MUST be implemented in such a way as to retain the
Chris@0 35 * immutability of the message, and MUST return an instance that has the
Chris@0 36 * new protocol version.
Chris@0 37 *
Chris@0 38 * @param string $version HTTP protocol version
Chris@0 39 * @return static
Chris@0 40 */
Chris@0 41 public function withProtocolVersion($version);
Chris@0 42
Chris@0 43 /**
Chris@0 44 * Retrieves all message header values.
Chris@0 45 *
Chris@0 46 * The keys represent the header name as it will be sent over the wire, and
Chris@0 47 * each value is an array of strings associated with the header.
Chris@0 48 *
Chris@0 49 * // Represent the headers as a string
Chris@0 50 * foreach ($message->getHeaders() as $name => $values) {
Chris@0 51 * echo $name . ": " . implode(", ", $values);
Chris@0 52 * }
Chris@0 53 *
Chris@0 54 * // Emit headers iteratively:
Chris@0 55 * foreach ($message->getHeaders() as $name => $values) {
Chris@0 56 * foreach ($values as $value) {
Chris@0 57 * header(sprintf('%s: %s', $name, $value), false);
Chris@0 58 * }
Chris@0 59 * }
Chris@0 60 *
Chris@0 61 * While header names are not case-sensitive, getHeaders() will preserve the
Chris@0 62 * exact case in which headers were originally specified.
Chris@0 63 *
Chris@0 64 * @return string[][] Returns an associative array of the message's headers. Each
Chris@0 65 * key MUST be a header name, and each value MUST be an array of strings
Chris@0 66 * for that header.
Chris@0 67 */
Chris@0 68 public function getHeaders();
Chris@0 69
Chris@0 70 /**
Chris@0 71 * Checks if a header exists by the given case-insensitive name.
Chris@0 72 *
Chris@0 73 * @param string $name Case-insensitive header field name.
Chris@0 74 * @return bool Returns true if any header names match the given header
Chris@0 75 * name using a case-insensitive string comparison. Returns false if
Chris@0 76 * no matching header name is found in the message.
Chris@0 77 */
Chris@0 78 public function hasHeader($name);
Chris@0 79
Chris@0 80 /**
Chris@0 81 * Retrieves a message header value by the given case-insensitive name.
Chris@0 82 *
Chris@0 83 * This method returns an array of all the header values of the given
Chris@0 84 * case-insensitive header name.
Chris@0 85 *
Chris@0 86 * If the header does not appear in the message, this method MUST return an
Chris@0 87 * empty array.
Chris@0 88 *
Chris@0 89 * @param string $name Case-insensitive header field name.
Chris@0 90 * @return string[] An array of string values as provided for the given
Chris@0 91 * header. If the header does not appear in the message, this method MUST
Chris@0 92 * return an empty array.
Chris@0 93 */
Chris@0 94 public function getHeader($name);
Chris@0 95
Chris@0 96 /**
Chris@0 97 * Retrieves a comma-separated string of the values for a single header.
Chris@0 98 *
Chris@0 99 * This method returns all of the header values of the given
Chris@0 100 * case-insensitive header name as a string concatenated together using
Chris@0 101 * a comma.
Chris@0 102 *
Chris@0 103 * NOTE: Not all header values may be appropriately represented using
Chris@0 104 * comma concatenation. For such headers, use getHeader() instead
Chris@0 105 * and supply your own delimiter when concatenating.
Chris@0 106 *
Chris@0 107 * If the header does not appear in the message, this method MUST return
Chris@0 108 * an empty string.
Chris@0 109 *
Chris@0 110 * @param string $name Case-insensitive header field name.
Chris@0 111 * @return string A string of values as provided for the given header
Chris@0 112 * concatenated together using a comma. If the header does not appear in
Chris@0 113 * the message, this method MUST return an empty string.
Chris@0 114 */
Chris@0 115 public function getHeaderLine($name);
Chris@0 116
Chris@0 117 /**
Chris@0 118 * Return an instance with the provided value replacing the specified header.
Chris@0 119 *
Chris@0 120 * While header names are case-insensitive, the casing of the header will
Chris@0 121 * be preserved by this function, and returned from getHeaders().
Chris@0 122 *
Chris@0 123 * This method MUST be implemented in such a way as to retain the
Chris@0 124 * immutability of the message, and MUST return an instance that has the
Chris@0 125 * new and/or updated header and value.
Chris@0 126 *
Chris@0 127 * @param string $name Case-insensitive header field name.
Chris@0 128 * @param string|string[] $value Header value(s).
Chris@0 129 * @return static
Chris@0 130 * @throws \InvalidArgumentException for invalid header names or values.
Chris@0 131 */
Chris@0 132 public function withHeader($name, $value);
Chris@0 133
Chris@0 134 /**
Chris@0 135 * Return an instance with the specified header appended with the given value.
Chris@0 136 *
Chris@0 137 * Existing values for the specified header will be maintained. The new
Chris@0 138 * value(s) will be appended to the existing list. If the header did not
Chris@0 139 * exist previously, it will be added.
Chris@0 140 *
Chris@0 141 * This method MUST be implemented in such a way as to retain the
Chris@0 142 * immutability of the message, and MUST return an instance that has the
Chris@0 143 * new header and/or value.
Chris@0 144 *
Chris@0 145 * @param string $name Case-insensitive header field name to add.
Chris@0 146 * @param string|string[] $value Header value(s).
Chris@0 147 * @return static
Chris@0 148 * @throws \InvalidArgumentException for invalid header names or values.
Chris@0 149 */
Chris@0 150 public function withAddedHeader($name, $value);
Chris@0 151
Chris@0 152 /**
Chris@0 153 * Return an instance without the specified header.
Chris@0 154 *
Chris@0 155 * Header resolution MUST be done without case-sensitivity.
Chris@0 156 *
Chris@0 157 * This method MUST be implemented in such a way as to retain the
Chris@0 158 * immutability of the message, and MUST return an instance that removes
Chris@0 159 * the named header.
Chris@0 160 *
Chris@0 161 * @param string $name Case-insensitive header field name to remove.
Chris@0 162 * @return static
Chris@0 163 */
Chris@0 164 public function withoutHeader($name);
Chris@0 165
Chris@0 166 /**
Chris@0 167 * Gets the body of the message.
Chris@0 168 *
Chris@0 169 * @return StreamInterface Returns the body as a stream.
Chris@0 170 */
Chris@0 171 public function getBody();
Chris@0 172
Chris@0 173 /**
Chris@0 174 * Return an instance with the specified message body.
Chris@0 175 *
Chris@0 176 * The body MUST be a StreamInterface object.
Chris@0 177 *
Chris@0 178 * This method MUST be implemented in such a way as to retain the
Chris@0 179 * immutability of the message, and MUST return a new instance that has the
Chris@0 180 * new body stream.
Chris@0 181 *
Chris@0 182 * @param StreamInterface $body Body.
Chris@0 183 * @return static
Chris@0 184 * @throws \InvalidArgumentException When the body is not valid.
Chris@0 185 */
Chris@0 186 public function withBody(StreamInterface $body);
Chris@0 187 }