searchpro / BerqWP / vendor / psr / http-message / src / RequestInterface.php

RequestInterface.php in BerqWP – All-In-One Optimization for Core Web Vitals, Cache, CDN, Images, CSS & JavaScript trunk, at BerqWP/vendor/psr/http-message/src/RequestInterface.php

131 lines 4.8 KB

Raw Download Zip

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