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