ServerRequestInterface.php — Independent Analytics – WordPress Analytics Plugin 2.15.0

independent-analytics / vendor / psr / http-message / src / ServerRequestInterface.php

independent-analytics / vendor / psr / http-message / src Last commit date

MessageInterface.php 2 years ago RequestInterface.php 2 years ago ResponseInterface.php 2 years ago ServerRequestInterface.php 2 years ago StreamInterface.php 2 years ago UploadedFileInterface.php 2 years ago UriInterface.php 2 years ago

ServerRequestInterface.php

252 lines

1	<?php
2
3	declare (strict_types=1);
4	namespace IAWPSCOPED\Psr\Http\Message;
5
6	/**
7	* Representation of an incoming, server-side HTTP request.
8	*
9	* Per the HTTP specification, this interface includes properties for
10	* each of the following:
11	*
12	* - Protocol version
13	* - HTTP method
14	* - URI
15	* - Headers
16	* - Message body
17	*
18	* Additionally, it encapsulates all data as it has arrived to the
19	* application from the CGI and/or PHP environment, including:
20	*
21	* - The values represented in $_SERVER.
22	* - Any cookies provided (generally via $_COOKIE)
23	* - Query string arguments (generally via $_GET, or as parsed via parse_str())
24	* - Upload files, if any (as represented by $_FILES)
25	* - Deserialized body parameters (generally from $_POST)
26	*
27	* $_SERVER values MUST be treated as immutable, as they represent application
28	* state at the time of request; as such, no methods are provided to allow
29	* modification of those values. The other values provide such methods, as they
30	* can be restored from $_SERVER or the request body, and may need treatment
31	* during the application (e.g., body parameters may be deserialized based on
32	* content type).
33	*
34	* Additionally, this interface recognizes the utility of introspecting a
35	* request to derive and match additional parameters (e.g., via URI path
36	* matching, decrypting cookie values, deserializing non-form-encoded body
37	* content, matching authorization headers to users, etc). These parameters
38	* are stored in an "attributes" property.
39	*
40	* Requests are considered immutable; all methods that might change state MUST
41	* be implemented such that they retain the internal state of the current
42	* message and return an instance that contains the changed state.
43	* @internal
44	*/
45	interface ServerRequestInterface extends RequestInterface
46	{
47	/**
48	* Retrieve server parameters.
49	*
50	* Retrieves data related to the incoming request environment,
51	* typically derived from PHP's $_SERVER superglobal. The data IS NOT
52	* REQUIRED to originate from $_SERVER.
53	*
54	* @return array
55	*/
56	public function getServerParams();
57	/**
58	* Retrieve cookies.
59	*
60	* Retrieves cookies sent by the client to the server.
61	*
62	* The data MUST be compatible with the structure of the $_COOKIE
63	* superglobal.
64	*
65	* @return array
66	*/
67	public function getCookieParams();
68	/**
69	* Return an instance with the specified cookies.
70	*
71	* The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST
72	* be compatible with the structure of $_COOKIE. Typically, this data will
73	* be injected at instantiation.
74	*
75	* This method MUST NOT update the related Cookie header of the request
76	* instance, nor related values in the server params.
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	* updated cookie values.
81	*
82	* @param array $cookies Array of key/value pairs representing cookies.
83	* @return static
84	*/
85	public function withCookieParams(array $cookies);
86	/**
87	* Retrieve query string arguments.
88	*
89	* Retrieves the deserialized query string arguments, if any.
90	*
91	* Note: the query params might not be in sync with the URI or server
92	* params. If you need to ensure you are only getting the original
93	* values, you may need to parse the query string from `getUri()->getQuery()`
94	* or from the `QUERY_STRING` server param.
95	*
96	* @return array
97	*/
98	public function getQueryParams();
99	/**
100	* Return an instance with the specified query string arguments.
101	*
102	* These values SHOULD remain immutable over the course of the incoming
103	* request. They MAY be injected during instantiation, such as from PHP's
104	* $_GET superglobal, or MAY be derived from some other value such as the
105	* URI. In cases where the arguments are parsed from the URI, the data
106	* MUST be compatible with what PHP's parse_str() would return for
107	* purposes of how duplicate query parameters are handled, and how nested
108	* sets are handled.
109	*
110	* Setting query string arguments MUST NOT change the URI stored by the
111	* request, nor the values in the server params.
112	*
113	* This method MUST be implemented in such a way as to retain the
114	* immutability of the message, and MUST return an instance that has the
115	* updated query string arguments.
116	*
117	* @param array $query Array of query string arguments, typically from
118	* $_GET.
119	* @return static
120	*/
121	public function withQueryParams(array $query);
122	/**
123	* Retrieve normalized file upload data.
124	*
125	* This method returns upload metadata in a normalized tree, with each leaf
126	* an instance of Psr\Http\Message\UploadedFileInterface.
127	*
128	* These values MAY be prepared from $_FILES or the message body during
129	* instantiation, or MAY be injected via withUploadedFiles().
130	*
131	* @return array An array tree of UploadedFileInterface instances; an empty
132	* array MUST be returned if no data is present.
133	*/
134	public function getUploadedFiles();
135	/**
136	* Create a new instance with the specified uploaded files.
137	*
138	* This method MUST be implemented in such a way as to retain the
139	* immutability of the message, and MUST return an instance that has the
140	* updated body parameters.
141	*
142	* @param array $uploadedFiles An array tree of UploadedFileInterface instances.
143	* @return static
144	* @throws \InvalidArgumentException if an invalid structure is provided.
145	*/
146	public function withUploadedFiles(array $uploadedFiles);
147	/**
148	* Retrieve any parameters provided in the request body.
149	*
150	* If the request Content-Type is either application/x-www-form-urlencoded
151	* or multipart/form-data, and the request method is POST, this method MUST
152	* return the contents of $_POST.
153	*
154	* Otherwise, this method may return any results of deserializing
155	* the request body content; as parsing returns structured content, the
156	* potential types MUST be arrays or objects only. A null value indicates
157	* the absence of body content.
158	*
159	* @return null\|array\|object The deserialized body parameters, if any.
160	* These will typically be an array or object.
161	*/
162	public function getParsedBody();
163	/**
164	* Return an instance with the specified body parameters.
165	*
166	* These MAY be injected during instantiation.
167	*
168	* If the request Content-Type is either application/x-www-form-urlencoded
169	* or multipart/form-data, and the request method is POST, use this method
170	* ONLY to inject the contents of $_POST.
171	*
172	* The data IS NOT REQUIRED to come from $_POST, but MUST be the results of
173	* deserializing the request body content. Deserialization/parsing returns
174	* structured data, and, as such, this method ONLY accepts arrays or objects,
175	* or a null value if nothing was available to parse.
176	*
177	* As an example, if content negotiation determines that the request data
178	* is a JSON payload, this method could be used to create a request
179	* instance with the deserialized parameters.
180	*
181	* This method MUST be implemented in such a way as to retain the
182	* immutability of the message, and MUST return an instance that has the
183	* updated body parameters.
184	*
185	* @param null\|array\|object $data The deserialized body data. This will
186	* typically be in an array or object.
187	* @return static
188	* @throws \InvalidArgumentException if an unsupported argument type is
189	* provided.
190	*/
191	public function withParsedBody($data);
192	/**
193	* Retrieve attributes derived from the request.
194	*
195	* The request "attributes" may be used to allow injection of any
196	* parameters derived from the request: e.g., the results of path
197	* match operations; the results of decrypting cookies; the results of
198	* deserializing non-form-encoded message bodies; etc. Attributes
199	* will be application and request specific, and CAN be mutable.
200	*
201	* @return array Attributes derived from the request.
202	*/
203	public function getAttributes();
204	/**
205	* Retrieve a single derived request attribute.
206	*
207	* Retrieves a single derived request attribute as described in
208	* getAttributes(). If the attribute has not been previously set, returns
209	* the default value as provided.
210	*
211	* This method obviates the need for a hasAttribute() method, as it allows
212	* specifying a default value to return if the attribute is not found.
213	*
214	* @see getAttributes()
215	* @param string $name The attribute name.
216	* @param mixed $default Default value to return if the attribute does not exist.
217	* @return mixed
218	*/
219	public function getAttribute(string $name, $default = null);
220	/**
221	* Return an instance with the specified derived request attribute.
222	*
223	* This method allows setting a single derived request attribute as
224	* described in getAttributes().
225	*
226	* This method MUST be implemented in such a way as to retain the
227	* immutability of the message, and MUST return an instance that has the
228	* updated attribute.
229	*
230	* @see getAttributes()
231	* @param string $name The attribute name.
232	* @param mixed $value The value of the attribute.
233	* @return static
234	*/
235	public function withAttribute(string $name, $value);
236	/**
237	* Return an instance that removes the specified derived request attribute.
238	*
239	* This method allows removing a single derived request attribute as
240	* described in getAttributes().
241	*
242	* This method MUST be implemented in such a way as to retain the
243	* immutability of the message, and MUST return an instance that removes
244	* the attribute.
245	*
246	* @see getAttributes()
247	* @param string $name The attribute name.
248	* @return static
249	*/
250	public function withoutAttribute(string $name);
251	}
252