Usage

The parsing/building algorithms preserve pairs order and uses the same algorithm used by JavaScript UrlSearchParams

Parsing the URI query string

Parsing a query string is easy.

<?php

use function League\Uri\query_parse;

$pairs = query_parse('module=home&action=show&page=😓');
// returns [
//     ['module', 'home'],
//     ['action', 'show'],
//     ['page', '😓']
// ];

Description

<?php

function League\Uri\query_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 League\Uri\query_parse parameters are

Here’s a simple example showing how to use all the given parameters:

<?php

use function League\Uri\query_parse;

$pairs = query_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 League\Uri\query_build function.

<?php

use function League\Uri\query_build;

$pairs = query_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

function League\Uri\query_build(iterable $pairs, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): ?string;

The League\Uri\query_build :

Just like with League\Uri\query_parse, you can specify the separator and the encoding algorithm to use.

Extracting PHP variables

League\Uri\query_parse and League\Uri\query_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 League\Uri\query_extract. The function:

<?php

use function League\Uri\query_extract;

$query = 'module=show&arr.test[1]=sid&arr test[4][two]=fred&+module+=hide';

$params = query_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.

<?php

use League\Uri\Parser\InvalidUriComponent;
use function League\Uri\query_extract;

try {
    query_extract('foo=bar', '&', 42);
} catch (InvalidUriComponent $e) {
    //$e is an instanceof League\Uri\Parser\UnknownEncoding
}