depicter / modules / Psr / Http / Message / UriInterface.php

UriInterface.php in Depicter — Popup & Slider Builder 1.9.2, at modules/Psr/Http/Message/UriInterface.php

324 lines 12.3 KB

Raw Download Zip

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