Proyectos de Subversion Moodle

Rev

| Ultima modificación | Ver Log |

Rev Autor Línea Nro. Línea
1 efrain 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(): string;
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 string $requestTarget
59 
     * @return static
60 
     */
61 
    public function withRequestTarget(string $requestTarget): RequestInterface;
62 
 
63 
 
64 
    /**
65 
     * Retrieves the HTTP method of the request.
66 
     *
67 
     * @return string Returns the request method.
68 
     */
69 
    public function getMethod(): string;
70 
 
71 
    /**
72 
     * Return an instance with the provided HTTP method.
73 
     *
74 
     * While HTTP method names are typically all uppercase characters, HTTP
75 
     * method names are case-sensitive and thus implementations SHOULD NOT
76 
     * modify the given string.
77 
     *
78 
     * This method MUST be implemented in such a way as to retain the
79 
     * immutability of the message, and MUST return an instance that has the
80 
     * changed request method.
81 
     *
82 
     * @param string $method Case-sensitive method.
83 
     * @return static
84 
     * @throws \InvalidArgumentException for invalid HTTP methods.
85 
     */
86 
    public function withMethod(string $method): RequestInterface;
87 
 
88 
    /**
89 
     * Retrieves the URI instance.
90 
     *
91 
     * This method MUST return a UriInterface instance.
92 
     *
93 
     * @link http://tools.ietf.org/html/rfc3986#section-4.3
94 
     * @return UriInterface Returns a UriInterface instance
95 
     *     representing the URI of the request.
96 
     */
97 
    public function getUri(): UriInterface;
98 
 
99 
    /**
100 
     * Returns an instance with the provided URI.
101 
     *
102 
     * This method MUST update the Host header of the returned request by
103 
     * default if the URI contains a host component. If the URI does not
104 
     * contain a host component, any pre-existing Host header MUST be carried
105 
     * over to the returned request.
106 
     *
107 
     * You can opt-in to preserving the original state of the Host header by
108 
     * setting `$preserveHost` to `true`. When `$preserveHost` is set to
109 
     * `true`, this method interacts with the Host header in the following ways:
110 
     *
111 
     * - If the Host header is missing or empty, and the new URI contains
112 
     *   a host component, this method MUST update the Host header in the returned
113 
     *   request.
114 
     * - If the Host header is missing or empty, and the new URI does not contain a
115 
     *   host component, this method MUST NOT update the Host header in the returned
116 
     *   request.
117 
     * - If a Host header is present and non-empty, this method MUST NOT update
118 
     *   the Host header in the returned request.
119 
     *
120 
     * This method MUST be implemented in such a way as to retain the
121 
     * immutability of the message, and MUST return an instance that has the
122 
     * new UriInterface instance.
123 
     *
124 
     * @link http://tools.ietf.org/html/rfc3986#section-4.3
125 
     * @param UriInterface $uri New request URI to use.
126 
     * @param bool $preserveHost Preserve the original state of the Host header.
127 
     * @return static
128 
     */
129 
    public function withUri(UriInterface $uri, bool $preserveHost = false): RequestInterface;
130 
}