1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
---
layout: default
title: URI Query string parser
redirect_from:
- /query-parser/
---
Uri Query String Parser and Builder
=======
[](https://travis-ci.org/thephpleague/uri-query-parser)
[](https://github.com/thephpleague/uri-query-parser/releases)
This package contains a userland PHP uri query parser and builder.
```php
<?php
use League\Uri\Parser\QueryString;
$pairs = QueryString::parse('module=home&action=show&page=😓');
// returns [
// ['module', 'home'],
// ['action', 'show'],
// ['page', '😓']
// ];
$str = QueryString::build($pairs, '|');
// returns 'module=home|action=show|page=😓'
```
System Requirements
-------
You need:
- **PHP >= 7.2** but the latest stable version of PHP is recommended
Installation
--------
```bash
$ composer require league/uri-query-parser
```
Usage
--------
<p class="message-notice">The parsing/building algorithms preserve pairs order and uses the same algorithm used by JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams">UrlSearchParams</a></p>
## Parsing the URI query string
Parsing a query string is easy.
```php
<?php
use League\Uri\Parser\QueryString;
$pairs = QueryString::parse('module=home&action=show&page=😓');
// returns [
// ['module', 'home'],
// ['action', 'show'],
// ['page', '😓']
// ];
```
### Description
```php
<?php
public static function QueryString::parse($query, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): array;
```
The returned array is a collection of key/value pairs. Each pair is represented as an array where the first element is the pair key and the second element the pair value. While the pair key is always a string, the pair value can be a string or the `null` value.
The `QueryString::parse` method parameters are
- `$query` can be the `null` value, any scalar or object which is stringable;
- `$separator` is a string; by default it is the `&` character;
- `$enc_type` is one of PHP's constant `PHP_QUERY_RFC3968` or `PHP_QUERY_RFC1738` which represented the supported encoding algoritm
- If you specify `PHP_QUERY_RFC3968` decoding will be done using [RFC3986](https://tools.ietf.org/html/rfc3986#section-3.4) rules;
- If you specify `PHP_QUERY_RFC1738` decoding will be done using [application/x-www-form-urlencoded](https://url.spec.whatwg.org/#urlencoded-parsing) rules;
Here's a simple example showing how to use all the given parameters:
```php
<?php
$pairs = QueryString::parse(
'module=home:action=show:page=toto+bar&action=hide',
':',
PHP_QUERY_RFC1738
);
// returns [
// ['module', 'home'],
// ['action', 'show'],
// ['page', 'toto bar'],
// ['action', 'hide'],
// ];
```
## Building the URI query string
To convert back the collection of key/value pairs into a valid query string or the `null` value you can use the static public `QueryString::build` method.
```php
<?php
$pairs = QueryString::build([
['module', 'home'],
['action', 'show'],
['page', 'toto bar'],
['action', 'hide'],
], '|', PHP_QUERY_RFC3986);
// returns 'module=home|action=show|page=toto%20bar|action=hide';
```
### Description
```php
<?php
public static function QueryString::build(iterable $pairs, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): ?string;
```
The static public `QueryString::build` method :
- accepts any iterable structure containing a collection of key/pair pairs as describe in the returned array of the `QueryString::parse` method.
Just like with `QueryString::parse`, you can specify the separator and the encoding algorithm to use.
- the function returns the `null` value if an empty array or collection is given as input.
## Extracting PHP variables
```php
<?php
public static function QueryString::extract($query, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): array;
public static function QueryString::convert(iterable $pairs): array;
```
`QueryString::parse` and `QueryString::build` preserve the query string pairs content and order. If you want to extract PHP variables from the query string *Ã la* `parse_str` you can use:
- The `QueryString::extract` method which takes the same parameters as `QueryString::parse`
- The `QueryString::convert` method which takes the result of `QueryString::parse`
both methods, however, do not allow parameters key mangling in the returned array like `parse_str`;
```php
<?php
use League\Uri\Parser\QueryString;
$query = 'module=show&arr.test[1]=sid&arr test[4][two]=fred&+module+=hide';
$params = QueryString::extract($query, '&', PHP_QUERY_RFC1738);
// $params contains [
// 'module' = 'show',
// 'arr.test' => [
// 1 => 'sid',
// ],
// 'arr test' => [
// 4 => [
// 'two' => 'fred',
// ]
// ],
// ' module ' => 'hide',
// ];
parse_str($query, $variables);
// $variables contains [
// 'module' = 'show',
// 'arr_test' => [
// 1 => 'sid',
// 4 => [
// 'two' => 'fred',
// ],
// ],
// 'module_' = 'hide',
// ];
```
## Exceptions
All exceptions extends the `League\Uri\Parser\InvalidUriComponent` marker class which extends PHP's `InvalidArgumentException` class.
- If the query string is invalid a `League\Uri\Exception\MalformedUriComponent` exception is thrown.
- If the query pair is invalid a `League\Uri\Parser\InvalidQueryPair` exception is thrown.
- If the encoding algorithm is unknown or invalid a `League\Uri\Parser\UnknownEncoding` exception is thrown.
```php
<?php
use League\Uri\Exception\InvalidUriComponent;
use League\Uri\Parser\QueryString;
try {
QueryString::extract('foo=bar', '&', 42);
} catch (InvalidUriComponent $e) {
//$e is an instanceof League\Uri\Parser\UnknownEncoding
}
```
|
