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();
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-2.7 (for the various
57: * request-target forms allowed in request messages)
58: * @param mixed $requestTarget
59: * @return self
60: */
61: public function withRequestTarget($requestTarget);
62:
63: /**
64: * Retrieves the HTTP method of the request.
65: *
66: * @return string Returns the request method.
67: */
68: public function getMethod();
69:
70: /**
71: * Return an instance with the provided HTTP method.
72: *
73: * While HTTP method names are typically all uppercase characters, HTTP
74: * method names are case-sensitive and thus implementations SHOULD NOT
75: * modify the given string.
76: *
77: * This method MUST be implemented in such a way as to retain the
78: * immutability of the message, and MUST return an instance that has the
79: * changed request method.
80: *
81: * @param string $method Case-sensitive method.
82: * @return self
83: * @throws \InvalidArgumentException for invalid HTTP methods.
84: */
85: public function withMethod($method);
86:
87: /**
88: * Retrieves the URI instance.
89: *
90: * This method MUST return a UriInterface instance.
91: *
92: * @link http://tools.ietf.org/html/rfc3986#section-4.3
93: * @return UriInterface Returns a UriInterface instance
94: * representing the URI of the request.
95: */
96: public function getUri();
97:
98: /**
99: * Returns an instance with the provided URI.
100: *
101: * This method MUST update the Host header of the returned request by
102: * default if the URI contains a host component. If the URI does not
103: * contain a host component, any pre-existing Host header MUST be carried
104: * over to the returned request.
105: *
106: * You can opt-in to preserving the original state of the Host header by
107: * setting `$preserveHost` to `true`. When `$preserveHost` is set to
108: * `true`, this method interacts with the Host header in the following ways:
109: *
110: * - If the the Host header is missing or empty, and the new URI contains
111: * a host component, this method MUST update the Host header in the returned
112: * request.
113: * - If the Host header is missing or empty, and the new URI does not contain a
114: * host component, this method MUST NOT update the Host header in the returned
115: * request.
116: * - If a Host header is present and non-empty, this method MUST NOT update
117: * the Host header in the returned request.
118: *
119: * This method MUST be implemented in such a way as to retain the
120: * immutability of the message, and MUST return an instance that has the
121: * new UriInterface instance.
122: *
123: * @link http://tools.ietf.org/html/rfc3986#section-4.3
124: * @param UriInterface $uri New request URI to use.
125: * @param bool $preserveHost Preserve the original state of the Host header.
126: * @return self
127: */
128: public function withUri(UriInterface $uri, $preserveHost = false);
129: }
130: