mantis-matrix-integration – Blame information for rev 1

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