[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace WordPress\AiClientDependencies\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       * Return an instance with the specific request-target.
  45       *
  46       * If the request needs a non-origin-form request-target — e.g., for
  47       * specifying an absolute-form, authority-form, or asterisk-form —
  48       * this method may be used to create an instance with the specified
  49       * request-target, verbatim.
  50       *
  51       * This method MUST be implemented in such a way as to retain the
  52       * immutability of the message, and MUST return an instance that has the
  53       * changed request target.
  54       *
  55       * @link http://tools.ietf.org/html/rfc7230#section-5.3 (for the various
  56       *     request-target forms allowed in request messages)
  57       * @param string $requestTarget
  58       * @return static
  59       */
  60      public function withRequestTarget(string $requestTarget): RequestInterface;
  61      /**
  62       * Retrieves the HTTP method of the request.
  63       *
  64       * @return string Returns the request method.
  65       */
  66      public function getMethod(): string;
  67      /**
  68       * Return an instance with the provided HTTP method.
  69       *
  70       * While HTTP method names are typically all uppercase characters, HTTP
  71       * method names are case-sensitive and thus implementations SHOULD NOT
  72       * modify the given string.
  73       *
  74       * This method MUST be implemented in such a way as to retain the
  75       * immutability of the message, and MUST return an instance that has the
  76       * changed request method.
  77       *
  78       * @param string $method Case-sensitive method.
  79       * @return static
  80       * @throws \InvalidArgumentException for invalid HTTP methods.
  81       */
  82      public function withMethod(string $method): RequestInterface;
  83      /**
  84       * Retrieves the URI instance.
  85       *
  86       * This method MUST return a UriInterface instance.
  87       *
  88       * @link http://tools.ietf.org/html/rfc3986#section-4.3
  89       * @return UriInterface Returns a UriInterface instance
  90       *     representing the URI of the request.
  91       */
  92      public function getUri(): UriInterface;
  93      /**
  94       * Returns an instance with the provided URI.
  95       *
  96       * This method MUST update the Host header of the returned request by
  97       * default if the URI contains a host component. If the URI does not
  98       * contain a host component, any pre-existing Host header MUST be carried
  99       * over to the returned request.
 100       *
 101       * You can opt-in to preserving the original state of the Host header by
 102       * setting `$preserveHost` to `true`. When `$preserveHost` is set to
 103       * `true`, this method interacts with the Host header in the following ways:
 104       *
 105       * - If the Host header is missing or empty, and the new URI contains
 106       *   a host component, this method MUST update the Host header in the returned
 107       *   request.
 108       * - If the Host header is missing or empty, and the new URI does not contain a
 109       *   host component, this method MUST NOT update the Host header in the returned
 110       *   request.
 111       * - If a Host header is present and non-empty, this method MUST NOT update
 112       *   the Host header in the returned request.
 113       *
 114       * This method MUST be implemented in such a way as to retain the
 115       * immutability of the message, and MUST return an instance that has the
 116       * new UriInterface instance.
 117       *
 118       * @link http://tools.ietf.org/html/rfc3986#section-4.3
 119       * @param UriInterface $uri New request URI to use.
 120       * @param bool $preserveHost Preserve the original state of the Host header.
 121       * @return static
 122       */
 123      public function withUri(UriInterface $uri, bool $preserveHost = \false): RequestInterface;
 124  }