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 * Representation of an outgoing, client-side request.
7 *
8 * Per the HTTP specification, this interface includes properties for
9 * each of the following:
10 *
11 * - Protocol version
12 * - HTTP method
13 * - URI
14 * - Headers
15 * - Message body
16 *
17 * During construction, implementations MUST attempt to set the Host header from
18 * a provided URI if no Host header is provided.
19 *
20 * Requests are considered immutable; all methods that might change state MUST
21 * be implemented such that they retain the internal state of the current
22 * message and return an instance that contains the changed state.
23 */
24 interface RequestInterface extends MessageInterface
25 {
26 /**
27 * Retrieves the message's request target.
28 *
29 * Retrieves the message's request-target either as it will appear (for
30 * clients), as it appeared at request (for servers), or as it was
31 * specified for the instance (see withRequestTarget()).
32 *
33 * In most cases, this will be the origin-form of the composed URI,
34 * unless a value was provided to the concrete implementation (see
35 * withRequestTarget() below).
36 *
37 * If no URI is available, and no request-target has been specifically
38 * provided, this method MUST return the string "/".
39 *
40 * @return string
41 */
42 public function getRequestTarget(): string;
43  
44 /**
45 * Return an instance with the specific request-target.
46 *
47 * If the request needs a non-origin-form request-target — e.g., for
48 * specifying an absolute-form, authority-form, or asterisk-form —
49 * this method may be used to create an instance with the specified
50 * request-target, verbatim.
51 *
52 * This method MUST be implemented in such a way as to retain the
53 * immutability of the message, and MUST return an instance that has the
54 * changed request target.
55 *
56 * @link http://tools.ietf.org/html/rfc7230#section-5.3 (for the various
57 * request-target forms allowed in request messages)
58 * @param string $requestTarget
59 * @return static
60 */
61 public function withRequestTarget(string $requestTarget): RequestInterface;
62  
63  
64 /**
65 * Retrieves the HTTP method of the request.
66 *
67 * @return string Returns the request method.
68 */
69 public function getMethod(): string;
70  
71 /**
72 * Return an instance with the provided HTTP method.
73 *
74 * While HTTP method names are typically all uppercase characters, HTTP
75 * method names are case-sensitive and thus implementations SHOULD NOT
76 * modify the given string.
77 *
78 * This method MUST be implemented in such a way as to retain the
79 * immutability of the message, and MUST return an instance that has the
80 * changed request method.
81 *
82 * @param string $method Case-sensitive method.
83 * @return static
84 * @throws \InvalidArgumentException for invalid HTTP methods.
85 */
86 public function withMethod(string $method): RequestInterface;
87  
88 /**
89 * Retrieves the URI instance.
90 *
91 * This method MUST return a UriInterface instance.
92 *
93 * @link http://tools.ietf.org/html/rfc3986#section-4.3
94 * @return UriInterface Returns a UriInterface instance
95 * representing the URI of the request.
96 */
97 public function getUri(): UriInterface;
98  
99 /**
100 * Returns an instance with the provided URI.
101 *
102 * This method MUST update the Host header of the returned request by
103 * default if the URI contains a host component. If the URI does not
104 * contain a host component, any pre-existing Host header MUST be carried
105 * over to the returned request.
106 *
107 * You can opt-in to preserving the original state of the Host header by
108 * setting `$preserveHost` to `true`. When `$preserveHost` is set to
109 * `true`, this method interacts with the Host header in the following ways:
110 *
111 * - If the Host header is missing or empty, and the new URI contains
112 * a host component, this method MUST update the Host header in the returned
113 * request.
114 * - If the Host header is missing or empty, and the new URI does not contain a
115 * host component, this method MUST NOT update the Host header in the returned
116 * request.
117 * - If a Host header is present and non-empty, this method MUST NOT update
118 * the Host header in the returned request.
119 *
120 * This method MUST be implemented in such a way as to retain the
121 * immutability of the message, and MUST return an instance that has the
122 * new UriInterface instance.
123 *
124 * @link http://tools.ietf.org/html/rfc3986#section-4.3
125 * @param UriInterface $uri New request URI to use.
126 * @param bool $preserveHost Preserve the original state of the Host header.
127 * @return static
128 */
129 public function withUri(UriInterface $uri, bool $preserveHost = false): RequestInterface;
130 }