[Summary view]

   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-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  }