annotate vendor/psr/http-message/src/RequestInterface.php @ 19:fa3358dc1485 tip

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