parse_str()

La fonction PHP parse_str() analyse une chaîne de requête URL (la partie après le ? dans une URL, comme name=John&age=35) et transforme chaque paire clé=valeur en une entrée dans un tableau. C'est l'inverse de http_build_query() : l'une construit une chaîne de requête, l'autre la décompose.

Cette page couvre la syntaxe de la fonction, un exemple de base, la gestion des tableaux et des clés imbriquées, les règles de décodage des URL, ainsi qu'une note de sécurité importante concernant son second argument.

Syntaxe

parse_str(string $string, array &$result): void

parse_str() prend deux paramètres :

• $string — la chaîne de requête à analyser, par exemple name=John&age=35.
• &$result — une variable, passée par référence, que la fonction remplit avec les paires clé/valeur analysées. Elle est écrasée par un nouveau tableau à chaque appel.

La fonction ne retourne rien (void) ; les données analysées sont écrites dans $result.

Remarque : dans les anciennes versions de PHP, l'argument $result était optionnel, et son omission importait chaque paire directement dans les variables locales. Ce comportement a été déprécié en PHP 7.2 et supprimé en PHP 8.0 — $result est désormais obligatoire. Pensez toujours à le passer.

Exemple de base

Ici, $query contient une chaîne de requête. parse_str() la divise sur &, décode chaque valeur et stocke le résultat dans $output. Le résultat est :

Array
(
    [name] => John Doe
    [age] => 35
    [gender] => male
)

Notez que John+Doe est devenu John Doe : parse_str() applique le même décodage d'URL que urldecode(), donc un + devient un espace et les séquences d'échappement %XX sont développées.

Analyse des tableaux et des clés imbriquées

Les chaînes de requête utilisent souvent [] pour exprimer des tableaux, exactement comme les champs de formulaire HTML nommés colors[] ou user[name]. parse_str() comprend cette notation entre crochets et construit automatiquement des tableaux imbriqués :

<?php
$query = 'colors[]=red&colors[]=blue&user[name]=Sam&user[age]=20';
parse_str($query, $output);
print_r($output);
?>

Résultat :

Array
(
    [colors] => Array
        (
            [0] => red
            [1] => blue
        )

    [user] => Array
        (
            [name] => Sam
            [age] => 20
        )

)

C'est la même analyse que PHP applique à $_GET et $_POST, c'est pourquoi un champ de formulaire nommé user[name] arrive sous la forme $_POST['user']['name'].

Lecture de la chaîne de requête depuis une URL

Un schéma courant consiste à extraire la chaîne de requête d'une URL complète avec parse_url() et à la passer ensuite à parse_str() :

<?php
$url = 'https://example.com/search?term=php&page=2';
parse_str(parse_url($url, PHP_URL_QUERY), $params);
print_r($params);
?>

Résultat :

Array
(
    [term] => php
    [page] => 2
)

Pour la chaîne de requête de la requête actuelle, vous n'avez généralement pas besoin de parse_str() du tout — PHP a déjà rempli $_GET. Utilisez parse_str() lorsque la chaîne de requête provient d'ailleurs : une URL stockée, une réponse d'API ou un payload webhook.

Note de sécurité

Lorsque le second argument est le tableau de résultat (comme indiqué ci-dessus), parse_str() est sûre et prévisible. Le danger n'existait qu'avec la forme à un seul argument désormais supprimée, qui injectait des variables directement dans la portée locale — une entrée non fiable pouvait écraser des variables existantes (une variante de l'ancien problème register_globals). Étant donné que PHP 8.0 a supprimé cette forme, ce piège a disparu dans le code moderne, mais vous devez tout de même traiter toute valeur provenant d'une chaîne de requête comme une entrée utilisateur non fiable et la valider avant utilisation.

Fonctions associées

• explode() — diviser une chaîne sur un délimiteur lorsque vous avez besoin d'une liste plate plutôt que d'une analyse clé=valeur.
• implode() — rejoindre les éléments d'un tableau en une chaîne.
• str_getcsv() — analyser des chaînes au format CSV en tableaux.
• Gestion des formulaires PHP — comment $_GET et $_POST utilisent cette même analyse.

Pratique