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