aleph1.co.uk Git - yaffs-website/blob - vendor/psr/http-message/src/RequestInterface.php

   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 }