parse_str()

La funzione PHP parse_str() analizza una query string di un URL (la parte dopo il ? in un URL, come name=John&age=35) e trasforma ogni coppia chiave=valore in un elemento di un array. È l'inverso di http_build_query(): una costruisce la query string, l'altra la scompone.

Questa pagina illustra la sintassi della funzione, un esempio di base, la gestione di array e chiavi annidate, le regole di decodifica URL e un'importante nota sulla sicurezza relativa al secondo argomento.

Sintassi

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

parse_str() accetta due parametri:

• $string — la query string da analizzare, ad esempio name=John&age=35.
• &$result — una variabile, passata per riferimento, che la funzione riempie con le coppie chiave/valore analizzate. Viene sovrascritta con un nuovo array a ogni chiamata.

La funzione non restituisce nulla (void); i dati analizzati vengono scritti in $result.

Nota: nelle versioni più vecchie di PHP l'argomento $result era facoltativo e, se omesso, importava direttamente ciascuna coppia come variabile locale. Questo comportamento è stato deprecato in PHP 7.2 e rimosso in PHP 8.0 — $result è ora obbligatorio. Passarlo sempre.

Esempio di base

Qui $query contiene una query string. parse_str() la divide sul carattere &, decodifica ogni valore e memorizza il risultato in $output. L'output è:

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

Si noti che John+Doe è diventato John Doe: parse_str() applica la stessa decodifica URL di urldecode(), quindi un + diventa uno spazio e le sequenze di escape %XX vengono espanse.

Analisi di array e chiavi annidate

Le query string usano spesso [] per esprimere array, esattamente come i campi di un form HTML denominati colors[] o user[name]. parse_str() comprende questa notazione con parentesi quadre e costruisce automaticamente array annidati:

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

Output:

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

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

)

Si tratta dello stesso parsing che PHP applica a $_GET e $_POST, motivo per cui un campo form denominato user[name] arriva come $_POST['user']['name'].

Lettura della query string da un URL

Un pattern comune consiste nell'estrarre la query string da un URL completo con parse_url() e poi passarla 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);
?>

Output:

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

Per la query string della richiesta corrente di solito non è necessario usare parse_str() — PHP ha già popolato $_GET. Utilizzare parse_str() quando la query string proviene da altrove: un URL memorizzato, una risposta API o un payload webhook.

Nota sulla sicurezza

Quando il secondo argomento è l'array dei risultati (come mostrato sopra), parse_str() è sicura e prevedibile. Il pericolo esisteva solo con la forma a singolo argomento ora rimossa, che iniettava variabili direttamente nello scope locale — un input non attendibile poteva sovrascrivere variabili esistenti (una variante del vecchio problema register_globals). Poiché PHP 8.0 ha rimosso quella forma, questa trappola è scomparsa nel codice moderno, ma occorre comunque trattare qualsiasi valore proveniente da una query string come input utente non attendibile e validarlo prima dell'uso.

Funzioni correlate

• explode() — dividere una stringa su un delimitatore quando si ha bisogno di un elenco semplice anziché del parsing chiave=valore.
• implode() — unire gli elementi di un array in una stringa.
• str_getcsv() — analizzare stringhe in formato CSV in array.
• Gestione dei form PHP — come $_GET e $_POST usano lo stesso parsing.

Pratica