wordpress-seo / vendor_prefixed / psr / http-message / src / UriInterface.php

UriInterface.php in Yoast SEO – Advanced SEO with real-time guidance and built-in AI trunk, at vendor_prefixed/psr/http-message/src/UriInterface.php

310 lines 12.8 KB

Raw Download Zip

1	<?php
2
3	namespace YoastSEO_Vendor\Psr\Http\Message;
4
5	/**
6	* Value object representing a URI.
7	*
8	* This interface is meant to represent URIs according to RFC 3986 and to
9	* provide methods for most common operations. Additional functionality for
10	* working with URIs can be provided on top of the interface or externally.
11	* Its primary use is for HTTP requests, but may also be used in other
12	* contexts.
13	*
14	* Instances of this interface are considered immutable; all methods that
15	* might change state MUST be implemented such that they retain the internal
16	* state of the current instance and return an instance that contains the
17	* changed state.
18	*
19	* Typically the Host header will be also be present in the request message.
20	* For server-side requests, the scheme will typically be discoverable in the
21	* server parameters.
22	*
23	* @link http://tools.ietf.org/html/rfc3986 (the URI specification)
24	*/
25	interface UriInterface
26	{
27	/**
28	* Retrieve the scheme component of the URI.
29	*
30	* If no scheme is present, this method MUST return an empty string.
31	*
32	* The value returned MUST be normalized to lowercase, per RFC 3986
33	* Section 3.1.
34	*
35	* The trailing ":" character is not part of the scheme and MUST NOT be
36	* added.
37	*
38	* @see https://tools.ietf.org/html/rfc3986#section-3.1
39	* @return string The URI scheme.
40	*/
41	public function getScheme() : string;
42	/**
43	* Retrieve the authority component of the URI.
44	*
45	* If no authority information is present, this method MUST return an empty
46	* string.
47	*
48	* The authority syntax of the URI is:
49	*
50	* <pre>
51	* [user-info@]host[:port]
52	* </pre>
53	*
54	* If the port component is not set or is the standard port for the current
55	* scheme, it SHOULD NOT be included.
56	*
57	* @see https://tools.ietf.org/html/rfc3986#section-3.2
58	* @return string The URI authority, in "[user-info@]host[:port]" format.
59	*/
60	public function getAuthority() : string;
61	/**
62	* Retrieve the user information component of the URI.
63	*
64	* If no user information is present, this method MUST return an empty
65	* string.
66	*
67	* If a user is present in the URI, this will return that value;
68	* additionally, if the password is also present, it will be appended to the
69	* user value, with a colon (":") separating the values.
70	*
71	* The trailing "@" character is not part of the user information and MUST
72	* NOT be added.
73	*
74	* @return string The URI user information, in "username[:password]" format.
75	*/
76	public function getUserInfo() : string;
77	/**
78	* Retrieve the host component of the URI.
79	*
80	* If no host is present, this method MUST return an empty string.
81	*
82	* The value returned MUST be normalized to lowercase, per RFC 3986
83	* Section 3.2.2.
84	*
85	* @see http://tools.ietf.org/html/rfc3986#section-3.2.2
86	* @return string The URI host.
87	*/
88	public function getHost() : string;
89	/**
90	* Retrieve the port component of the URI.
91	*
92	* If a port is present, and it is non-standard for the current scheme,
93	* this method MUST return it as an integer. If the port is the standard port
94	* used with the current scheme, this method SHOULD return null.
95	*
96	* If no port is present, and no scheme is present, this method MUST return
97	* a null value.
98	*
99	* If no port is present, but a scheme is present, this method MAY return
100	* the standard port for that scheme, but SHOULD return null.
101	*
102	* @return null\|int The URI port.
103	*/
104	public function getPort() : ?int;
105	/**
106	* Retrieve the path component of the URI.
107	*
108	* The path can either be empty or absolute (starting with a slash) or
109	* rootless (not starting with a slash). Implementations MUST support all
110	* three syntaxes.
111	*
112	* Normally, the empty path "" and absolute path "/" are considered equal as
113	* defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically
114	* do this normalization because in contexts with a trimmed base path, e.g.
115	* the front controller, this difference becomes significant. It's the task
116	* of the user to handle both "" and "/".
117	*
118	* The value returned MUST be percent-encoded, but MUST NOT double-encode
119	* any characters. To determine what characters to encode, please refer to
120	* RFC 3986, Sections 2 and 3.3.
121	*
122	* As an example, if the value should include a slash ("/") not intended as
123	* delimiter between path segments, that value MUST be passed in encoded
124	* form (e.g., "%2F") to the instance.
125	*
126	* @see https://tools.ietf.org/html/rfc3986#section-2
127	* @see https://tools.ietf.org/html/rfc3986#section-3.3
128	* @return string The URI path.
129	*/
130	public function getPath() : string;
131	/**
132	* Retrieve the query string of the URI.
133	*
134	* If no query string is present, this method MUST return an empty string.
135	*
136	* The leading "?" character is not part of the query and MUST NOT be
137	* added.
138	*
139	* The value returned MUST be percent-encoded, but MUST NOT double-encode
140	* any characters. To determine what characters to encode, please refer to
141	* RFC 3986, Sections 2 and 3.4.
142	*
143	* As an example, if a value in a key/value pair of the query string should
144	* include an ampersand ("&") not intended as a delimiter between values,
145	* that value MUST be passed in encoded form (e.g., "%26") to the instance.
146	*
147	* @see https://tools.ietf.org/html/rfc3986#section-2
148	* @see https://tools.ietf.org/html/rfc3986#section-3.4
149	* @return string The URI query string.
150	*/
151	public function getQuery() : string;
152	/**
153	* Retrieve the fragment component of the URI.
154	*
155	* If no fragment is present, this method MUST return an empty string.
156	*
157	* The leading "#" character is not part of the fragment and MUST NOT be
158	* added.
159	*
160	* The value returned MUST be percent-encoded, but MUST NOT double-encode
161	* any characters. To determine what characters to encode, please refer to
162	* RFC 3986, Sections 2 and 3.5.
163	*
164	* @see https://tools.ietf.org/html/rfc3986#section-2
165	* @see https://tools.ietf.org/html/rfc3986#section-3.5
166	* @return string The URI fragment.
167	*/
168	public function getFragment() : string;
169	/**
170	* Return an instance with the specified scheme.
171	*
172	* This method MUST retain the state of the current instance, and return
173	* an instance that contains the specified scheme.
174	*
175	* Implementations MUST support the schemes "http" and "https" case
176	* insensitively, and MAY accommodate other schemes if required.
177	*
178	* An empty scheme is equivalent to removing the scheme.
179	*
180	* @param string $scheme The scheme to use with the new instance.
181	* @return static A new instance with the specified scheme.
182	* @throws \InvalidArgumentException for invalid or unsupported schemes.
183	*/
184	public function withScheme(string $scheme) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
185	/**
186	* Return an instance with the specified user information.
187	*
188	* This method MUST retain the state of the current instance, and return
189	* an instance that contains the specified user information.
190	*
191	* Password is optional, but the user information MUST include the
192	* user; an empty string for the user is equivalent to removing user
193	* information.
194	*
195	* @param string $user The user name to use for authority.
196	* @param null\|string $password The password associated with $user.
197	* @return static A new instance with the specified user information.
198	*/
199	public function withUserInfo(string $user, ?string $password = null) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
200	/**
201	* Return an instance with the specified host.
202	*
203	* This method MUST retain the state of the current instance, and return
204	* an instance that contains the specified host.
205	*
206	* An empty host value is equivalent to removing the host.
207	*
208	* @param string $host The hostname to use with the new instance.
209	* @return static A new instance with the specified host.
210	* @throws \InvalidArgumentException for invalid hostnames.
211	*/
212	public function withHost(string $host) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
213	/**
214	* Return an instance with the specified port.
215	*
216	* This method MUST retain the state of the current instance, and return
217	* an instance that contains the specified port.
218	*
219	* Implementations MUST raise an exception for ports outside the
220	* established TCP and UDP port ranges.
221	*
222	* A null value provided for the port is equivalent to removing the port
223	* information.
224	*
225	* @param null\|int $port The port to use with the new instance; a null value
226	* removes the port information.
227	* @return static A new instance with the specified port.
228	* @throws \InvalidArgumentException for invalid ports.
229	*/
230	public function withPort(?int $port) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
231	/**
232	* Return an instance with the specified path.
233	*
234	* This method MUST retain the state of the current instance, and return
235	* an instance that contains the specified path.
236	*
237	* The path can either be empty or absolute (starting with a slash) or
238	* rootless (not starting with a slash). Implementations MUST support all
239	* three syntaxes.
240	*
241	* If the path is intended to be domain-relative rather than path relative then
242	* it must begin with a slash ("/"). Paths not starting with a slash ("/")
243	* are assumed to be relative to some base path known to the application or
244	* consumer.
245	*
246	* Users can provide both encoded and decoded path characters.
247	* Implementations ensure the correct encoding as outlined in getPath().
248	*
249	* @param string $path The path to use with the new instance.
250	* @return static A new instance with the specified path.
251	* @throws \InvalidArgumentException for invalid paths.
252	*/
253	public function withPath(string $path) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
254	/**
255	* Return an instance with the specified query string.
256	*
257	* This method MUST retain the state of the current instance, and return
258	* an instance that contains the specified query string.
259	*
260	* Users can provide both encoded and decoded query characters.
261	* Implementations ensure the correct encoding as outlined in getQuery().
262	*
263	* An empty query string value is equivalent to removing the query string.
264	*
265	* @param string $query The query string to use with the new instance.
266	* @return static A new instance with the specified query string.
267	* @throws \InvalidArgumentException for invalid query strings.
268	*/
269	public function withQuery(string $query) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
270	/**
271	* Return an instance with the specified URI fragment.
272	*
273	* This method MUST retain the state of the current instance, and return
274	* an instance that contains the specified URI fragment.
275	*
276	* Users can provide both encoded and decoded fragment characters.
277	* Implementations ensure the correct encoding as outlined in getFragment().
278	*
279	* An empty fragment value is equivalent to removing the fragment.
280	*
281	* @param string $fragment The fragment to use with the new instance.
282	* @return static A new instance with the specified fragment.
283	*/
284	public function withFragment(string $fragment) : \YoastSEO_Vendor\Psr\Http\Message\UriInterface;
285	/**
286	* Return the string representation as a URI reference.
287	*
288	* Depending on which components of the URI are present, the resulting
289	* string is either a full URI or relative reference according to RFC 3986,
290	* Section 4.1. The method concatenates the various components of the URI,
291	* using the appropriate delimiters:
292	*
293	* - If a scheme is present, it MUST be suffixed by ":".
294	* - If an authority is present, it MUST be prefixed by "//".
295	* - The path can be concatenated without delimiters. But there are two
296	* cases where the path has to be adjusted to make the URI reference
297	* valid as PHP does not allow to throw an exception in __toString():
298	* - If the path is rootless and an authority is present, the path MUST
299	* be prefixed by "/".
300	* - If the path is starting with more than one "/" and no authority is
301	* present, the starting slashes MUST be reduced to one.
302	* - If a query is present, it MUST be prefixed by "?".
303	* - If a fragment is present, it MUST be prefixed by "#".
304	*
305	* @see http://tools.ietf.org/html/rfc3986#section-4.1
306	* @return string
307	*/
308	public function __toString() : string;
309	}
310