[Summary view] [Print] [Text view]

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