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

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

228 lines 7.1 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	/**
17	* @extends \IteratorAggregate<array{0:string, 1:string\|null}>
18	*/
19	interface QueryInterface extends \Countable, \IteratorAggregate, UriComponentInterface
20	{
21	/**
22	* Returns the query separator.
23	*/
24	public function getSeparator(): string;
25
26	/**
27	* Returns the number of key/value pairs present in the object.
28	*/
29	public function count(): int;
30
31	/**
32	* Returns an iterator allowing to go through all key/value pairs contained in this object.
33	*
34	* The pair is represented as an array where the first value is the pair key
35	* and the second value the pair value.
36	*
37	* The key of each pair is a string
38	* The value of each pair is a scalar or the null value
39	*
40	* @return \Iterator<int, array{0:string, 1:string\|null}>
41	*/
42	public function getIterator(): \Iterator;
43
44	/**
45	* Returns an iterator allowing to go through all key/value pairs contained in this object.
46	*
47	* The return type is as a Iterator where its offset is the pair key and its value the pair value.
48	*
49	* The key of each pair is a string
50	* The value of each pair is a scalar or the null value
51	*
52	* @return iterable<string, string\|null>
53	*/
54	public function pairs(): iterable;
55
56	/**
57	* Tells whether a pair with a specific name exists.
58	*
59	* @see https://url.spec.whatwg.org/#dom-urlsearchparams-has
60	*/
61	public function has(string $key): bool;
62
63	/**
64	* Returns the first value associated to the given pair name.
65	*
66	* If no value is found null is returned
67	*
68	* @see https://url.spec.whatwg.org/#dom-urlsearchparams-get
69	*/
70	public function get(string $key): ?string;
71
72	/**
73	* Returns all the values associated to the given pair name as an array or all
74	* the instance pairs.
75	*
76	* If no value is found an empty array is returned
77	*
78	* @see https://url.spec.whatwg.org/#dom-urlsearchparams-getall
79	*
80	* @return array<int, string\|null>
81	*/
82	public function getAll(string $key): array;
83
84	/**
85	* Returns the store PHP variables as elements of an array.
86	*
87	* The result is similar as PHP parse_str when used with its
88	* second argument with the difference that variable names are
89	* not mangled.
90	*
91	* If a key is submitted it will returns the value attached to it or null
92	*
93	* @see http://php.net/parse_str
94	* @see https://wiki.php.net/rfc/on_demand_name_mangling
95	*
96	* @param ?string $key
97	* @return mixed the collection of stored PHP variables or the empty array if no input is given,
98	* the single value of a stored PHP variable or null if the variable is not present in the collection
99	*/
100	public function params(?string $key = null);
101
102	/**
103	* Returns the RFC1738 encoded query.
104	*/
105	public function toRFC1738(): ?string;
106
107	/**
108	* Returns the RFC3986 encoded query.
109	*
110	* @see ::getContent
111	*/
112	public function toRFC3986(): ?string;
113
114	/**
115	* Returns an instance with a different separator.
116	*
117	* This method MUST retain the state of the current instance, and return
118	* an instance that contains the query component with a different separator
119	*/
120	public function withSeparator(string $separator): self;
121
122	/**
123	* Sorts the query string by offset, maintaining offset to data correlations.
124	*
125	* This method MUST retain the state of the current instance, and return
126	* an instance that contains the modified query
127	*
128	* @see https://url.spec.whatwg.org/#dom-urlsearchparams-sort
129	*/
130	public function sort(): self;
131
132	/**
133	* Returns an instance without duplicate key/value pair.
134	*
135	* This method MUST retain the state of the current instance, and return
136	* an instance that contains the query component normalized by removing
137	* duplicate pairs whose key/value are the same.
138	*/
139	public function withoutDuplicates(): self;
140
141	/**
142	* Returns an instance without empty key/value where the value is the null value.
143	*
144	* This method MUST retain the state of the current instance, and return
145	* an instance that contains the query component normalized by removing
146	* empty pairs.
147	*
148	* A pair is considered empty if its value is equal to the null value
149	*/
150	public function withoutEmptyPairs(): self;
151
152	/**
153	* Returns an instance where numeric indices associated to PHP's array like key are removed.
154	*
155	* This method MUST retain the state of the current instance, and return
156	* an instance that contains the query component normalized so that numeric indexes
157	* are removed from the pair key value.
158	*
159	* ie.: toto[3]=bar[3]&foo=bar becomes toto[]=bar[3]&foo=bar
160	*/
161	public function withoutNumericIndices(): self;
162
163	/**
164	* Returns an instance with the a new key/value pair added to it.
165	*
166	* This method MUST retain the state of the current instance, and return
167	* an instance that contains the modified query
168	*
169	* If the pair already exists the value will replace the existing value.
170	*
171	* @see https://url.spec.whatwg.org/#dom-urlsearchparams-set
172	*
173	* @param ?string $value
174	*/
175	public function withPair(string $key, ?string $value): self;
176
177	/**
178	* Returns an instance with the new pairs set to it.
179	*
180	* This method MUST retain the state of the current instance, and return
181	* an instance that contains the modified query
182	*
183	* @see ::withPair
184	*/
185	public function merge(string $query): self;
186
187	/**
188	* Returns an instance without the specified keys.
189	*
190	* This method MUST retain the state of the current instance, and return
191	* an instance that contains the modified component
192	*
193	* @param string ...$keys
194	*/
195	public function withoutPair(string ...$keys): self;
196
197	/**
198	* Returns a new instance with a specified key/value pair appended as a new pair.
199	*
200	* This method MUST retain the state of the current instance, and return
201	* an instance that contains the modified query
202	*
203	* @param ?string $value
204	*/
205	public function appendTo(string $key, ?string $value): self;
206
207	/**
208	* Returns an instance with the new pairs appended to it.
209	*
210	* This method MUST retain the state of the current instance, and return
211	* an instance that contains the modified query
212	*
213	* If the pair already exists the value will be added to it.
214	*/
215	public function append(string $query): self;
216
217	/**
218	* Returns an instance without the specified params.
219	*
220	* This method MUST retain the state of the current instance, and return
221	* an instance that contains the modified component without PHP's value.
222	* PHP's mangled is not taken into account.
223	*
224	* @param string ...$keys
225	*/
226	public function withoutParam(string ...$keys): self;
227	}
228