[Summary view]

Differences Between: [Versions 311 and 403] [Versions 400 and 403] [Versions 401 and 403] [Versions 402 and 403]

   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  }