parse_str()

La función parse_str() de PHP analiza una cadena de consulta URL (la parte después del ? en una URL, como name=John&age=35) y convierte cada par clave=valor en una entrada de un array. Es la inversa de http_build_query(): una construye una cadena de consulta, la otra la descompone.

Esta página cubre la sintaxis de la función, un ejemplo básico, cómo maneja arrays y claves anidadas, reglas de decodificación de URL y una nota importante de seguridad sobre su segundo argumento.

Sintaxis

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

parse_str() acepta dos parámetros:

• $string — la cadena de consulta a analizar, por ejemplo name=John&age=35.
• &$result — una variable, pasada por referencia, que la función rellena con los pares clave/valor analizados. Se sobreescribe con un array nuevo en cada llamada.

La función no devuelve nada (void); los datos analizados se escriben en $result.

Nota: en versiones antiguas de PHP el argumento $result era opcional, y omitirlo importaba cada par directamente como variables locales. Ese comportamiento se deprecó en PHP 7.2 y se eliminó en PHP 8.0 — $result ahora es obligatorio. Pásalo siempre.

Ejemplo básico

Aquí $query contiene una cadena de consulta. parse_str() la divide por &, decodifica cada valor y almacena el resultado en $output. La salida es:

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

Observa que John+Doe se convirtió en John Doe: parse_str() aplica la misma decodificación de URL que urldecode(), por lo que un + se convierte en espacio y las secuencias de escape %XX se expanden.

Análisis de arrays y claves anidadas

Las cadenas de consulta suelen usar [] para expresar arrays, exactamente como los campos de formulario HTML llamados colors[] o user[name]. parse_str() entiende esta notación con corchetes y construye arrays anidados automáticamente:

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

Salida:

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

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

)

Este es el mismo análisis que PHP aplica a $_GET y $_POST, razón por la cual un campo de formulario llamado user[name] llega como $_POST['user']['name'].

Obtener la cadena de consulta de una URL

Un patrón habitual es extraer la cadena de consulta de una URL completa con parse_url() y luego pasársela a parse_str():

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

Salida:

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

Para la cadena de consulta de la petición actual normalmente no necesitas parse_str() — PHP ya ha llenado $_GET. Usa parse_str() cuando la cadena de consulta provenga de otro lugar: una URL almacenada, una respuesta de API o un payload de webhook.

Nota de seguridad

Cuando el segundo argumento es el array de resultado (como se muestra arriba), parse_str() es segura y predecible. El peligro existía únicamente con la forma de un solo argumento, ahora eliminada, que inyectaba variables directamente en el ámbito local — una entrada no confiable podía sobreescribir variables existentes (una variante del antiguo problema de register_globals). Como PHP 8.0 eliminó esa forma, este riesgo desaparece en código moderno, pero aun así debes tratar cualquier valor proveniente de una cadena de consulta como entrada de usuario no confiable y validarla antes de usarla.

Funciones relacionadas

• explode() — divide una cadena por un delimitador cuando necesitas una lista plana en lugar de un análisis clave=valor.
• implode() — une los elementos de un array en una cadena.
• str_getcsv() — analiza cadenas con formato CSV en arrays.
• Manejo de formularios PHP — cómo $_GET y $_POST usan este mismo análisis.

Práctica