defender-security / vendor / league / uri-interfaces / src / Contracts / UriInterface.php

UriInterface.php in Defender Security – Malware Scanner, Login Security & Firewall 5.6.2, at vendor/league/uri-interfaces/src/Contracts/UriInterface.php

293 lines 10.3 KB

Raw Download Zip

1	<?php
2
3	/**
4	* League.Uri (https://uri.thephpleague.com)
5	*
6	* (c) Ignace Nyamagana Butera <[email protected]>
7	*
8	* For the full copyright and license information, please view the LICENSE
9	* file that was distributed with this source code.
10	*/
11
12	declare(strict_types=1);
13
14	namespace League\Uri\Contracts;
15
16	use League\Uri\Exceptions\IdnSupportMissing;
17	use League\Uri\Exceptions\SyntaxError;
18
19	interface UriInterface extends \JsonSerializable
20	{
21	/**
22	* Returns the string representation as a URI reference.
23	*
24	* @see http://tools.ietf.org/html/rfc3986#section-4.1
25	*/
26	public function __toString(): string;
27
28	/**
29	* Returns the string representation as a URI reference.
30	*
31	* @see http://tools.ietf.org/html/rfc3986#section-4.1
32	* @see ::__toString
33	*/
34	public function jsonSerialize(): string;
35
36	/**
37	* Retrieve the scheme component of the URI.
38	*
39	* If no scheme is present, this method MUST return a null value.
40	*
41	* The value returned MUST be normalized to lowercase, per RFC 3986
42	* Section 3.1.
43	*
44	* The trailing ":" character is not part of the scheme and MUST NOT be
45	* added.
46	*
47	* @see https://tools.ietf.org/html/rfc3986#section-3.1
48	*/
49	public function getScheme(): ?string;
50
51	/**
52	* Retrieve the authority component of the URI.
53	*
54	* If no scheme is present, this method MUST return a null value.
55	*
56	* If the port component is not set or is the standard port for the current
57	* scheme, it SHOULD NOT be included.
58	*
59	* @see https://tools.ietf.org/html/rfc3986#section-3.2
60	*/
61	public function getAuthority(): ?string;
62
63	/**
64	* Retrieve the user information component of the URI.
65	*
66	* If no scheme is present, this method MUST return a null value.
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	public function getUserInfo(): ?string;
76
77	/**
78	* Retrieve the host component of the URI.
79	*
80	* If no host is present this method MUST return a null value.
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	*/
87	public function getHost(): ?string;
88
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	public function getPort(): ?int;
103
104	/**
105	* Retrieve the path component of the URI.
106	*
107	* The path can either be empty or absolute (starting with a slash) or
108	* rootless (not starting with a slash). Implementations MUST support all
109	* three syntaxes.
110	*
111	* Normally, the empty path "" and absolute path "/" are considered equal as
112	* defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically
113	* do this normalization because in contexts with a trimmed base path, e.g.
114	* the front controller, this difference becomes significant. It's the task
115	* of the user to handle both "" and "/".
116	*
117	* The value returned MUST be percent-encoded, but MUST NOT double-encode
118	* any characters. To determine what characters to encode, please refer to
119	* RFC 3986, Sections 2 and 3.3.
120	*
121	* As an example, if the value should include a slash ("/") not intended as
122	* delimiter between path segments, that value MUST be passed in encoded
123	* form (e.g., "%2F") to the instance.
124	*
125	* @see https://tools.ietf.org/html/rfc3986#section-2
126	* @see https://tools.ietf.org/html/rfc3986#section-3.3
127	*/
128	public function getPath(): string;
129
130	/**
131	* Retrieve the query string of the URI.
132	*
133	* If no host is present this method MUST return a null value.
134	*
135	* The leading "?" character is not part of the query and MUST NOT be
136	* added.
137	*
138	* The value returned MUST be percent-encoded, but MUST NOT double-encode
139	* any characters. To determine what characters to encode, please refer to
140	* RFC 3986, Sections 2 and 3.4.
141	*
142	* As an example, if a value in a key/value pair of the query string should
143	* include an ampersand ("&") not intended as a delimiter between values,
144	* that value MUST be passed in encoded form (e.g., "%26") to the instance.
145	*
146	* @see https://tools.ietf.org/html/rfc3986#section-2
147	* @see https://tools.ietf.org/html/rfc3986#section-3.4
148	*/
149	public function getQuery(): ?string;
150
151	/**
152	* Retrieve the fragment component of the URI.
153	*
154	* If no host is present this method MUST return a null value.
155	*
156	* The leading "#" character is not part of the fragment and MUST NOT be
157	* added.
158	*
159	* The value returned MUST be percent-encoded, but MUST NOT double-encode
160	* any characters. To determine what characters to encode, please refer to
161	* RFC 3986, Sections 2 and 3.5.
162	*
163	* @see https://tools.ietf.org/html/rfc3986#section-2
164	* @see https://tools.ietf.org/html/rfc3986#section-3.5
165	*/
166	public function getFragment(): ?string;
167
168	/**
169	* Return an instance with the specified scheme.
170	*
171	* This method MUST retain the state of the current instance, and return
172	* an instance that contains the specified scheme.
173	*
174	* A null value provided for the scheme is equivalent to removing the scheme
175	* information.
176	*
177	* @param ?string $scheme
178	*
179	* @throws SyntaxError for invalid component or transformations
180	* that would result in a object in invalid state.
181	*/
182	public function withScheme(?string $scheme): self;
183
184	/**
185	* Return an instance with the specified user information.
186	*
187	* This method MUST retain the state of the current instance, and return
188	* an instance that contains the specified user information.
189	*
190	* Password is optional, but the user information MUST include the
191	* user; a null value for the user is equivalent to removing user
192	* information.
193	*
194	* @param ?string $user
195	* @param ?string $password
196	*
197	* @throws SyntaxError for invalid component or transformations
198	* that would result in a object in invalid state.
199	*/
200	public function withUserInfo(?string $user, ?string $password = null): self;
201
202	/**
203	* Return an instance with the specified host.
204	*
205	* This method MUST retain the state of the current instance, and return
206	* an instance that contains the specified host.
207	*
208	* A null value provided for the host is equivalent to removing the host
209	* information.
210	*
211	* @param ?string $host
212	*
213	* @throws SyntaxError for invalid component or transformations
214	* that would result in a object in invalid state.
215	* @throws IdnSupportMissing for component or transformations
216	* requiring IDN support when IDN support is not present
217	* or misconfigured.
218	*/
219	public function withHost(?string $host): self;
220
221	/**
222	* Return an instance with the specified port.
223	*
224	* This method MUST retain the state of the current instance, and return
225	* an instance that contains the specified port.
226	*
227	* A null value provided for the port is equivalent to removing the port
228	* information.
229	*
230	* @param ?int $port
231	*
232	* @throws SyntaxError for invalid component or transformations
233	* that would result in a object in invalid state.
234	*/
235	public function withPort(?int $port): self;
236
237	/**
238	* Return an instance with the specified path.
239	*
240	* This method MUST retain the state of the current instance, and return
241	* an instance that contains the specified path.
242	*
243	* The path can either be empty or absolute (starting with a slash) or
244	* rootless (not starting with a slash). Implementations MUST support all
245	* three syntaxes.
246	*
247	* Users can provide both encoded and decoded path characters.
248	* Implementations ensure the correct encoding as outlined in getPath().
249	*
250	* @throws SyntaxError for invalid component or transformations
251	* that would result in a object in invalid state.
252	*/
253	public function withPath(string $path): self;
254
255	/**
256	* Return an instance with the specified query string.
257	*
258	* This method MUST retain the state of the current instance, and return
259	* an instance that contains the specified query string.
260	*
261	* Users can provide both encoded and decoded query characters.
262	* Implementations ensure the correct encoding as outlined in getQuery().
263	*
264	* A null value provided for the query is equivalent to removing the query
265	* information.
266	*
267	* @param ?string $query
268	*
269	* @throws SyntaxError for invalid component or transformations
270	* that would result in a object in invalid state.
271	*/
272	public function withQuery(?string $query): self;
273
274	/**
275	* Return an instance with the specified URI fragment.
276	*
277	* This method MUST retain the state of the current instance, and return
278	* an instance that contains the specified URI fragment.
279	*
280	* Users can provide both encoded and decoded fragment characters.
281	* Implementations ensure the correct encoding as outlined in getFragment().
282	*
283	* A null value provided for the fragment is equivalent to removing the fragment
284	* information.
285	*
286	* @param ?string $fragment
287	*
288	* @throws SyntaxError for invalid component or transformations
289	* that would result in a object in invalid state.
290	*/
291	public function withFragment(?string $fragment): self;
292	}
293