krz/vox-populi

  1<?php
  2
  3namespace 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 */
 24interface 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-5.3 (for the various
 57     *     request-target forms allowed in request messages)
 58     * @param mixed $requestTarget
 59     * @return static
 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 static
 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 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 static
127     */
128    public function withUri(UriInterface $uri, $preserveHost = false);
129}