parse_str()

A função PHP parse_str() analisa uma string de consulta de URL (a parte após o ? em uma URL, como name=John&age=35) e transforma cada par key=value em uma entrada em um array. É o inverso de http_build_query(): uma constrói uma string de consulta, a outra a desmonta.

Esta página cobre a sintaxe da função, um exemplo básico, como ela lida com arrays e chaves aninhadas, regras de decodificação de URL e uma nota importante de segurança sobre o segundo argumento.

Sintaxe

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

parse_str() recebe dois parâmetros:

• $string — a string de consulta a ser analisada, por exemplo name=John&age=35.
• &$result — uma variável, passada por referência, que a função preenche com os pares chave/valor analisados. É sobrescrita com um novo array a cada chamada.

A função não retorna nada (void); os dados analisados são gravados em $result.

Nota: em versões mais antigas do PHP, o argumento $result era opcional, e omiti-lo importava cada par diretamente para variáveis locais. Esse comportamento foi descontinuado no PHP 7.2 e removido no PHP 8.0 — $result agora é obrigatório. Sempre passe-o.

Exemplo básico

Aqui $query contém uma string de consulta. parse_str() a divide em &, decodifica cada valor e armazena o resultado em $output. A saída é:

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

Note que John+Doe tornou-se John Doe: parse_str() aplica a mesma decodificação de URL que urldecode(), portanto um + torna-se um espaço e as sequências de escape %XX são expandidas.

Analisando arrays e chaves aninhadas

Strings de consulta frequentemente usam [] para expressar arrays, exatamente como campos de formulário HTML com nomes colors[] ou user[name]. parse_str() entende essa notação de colchetes e constrói arrays aninhados automaticamente:

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

Saída:

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

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

)

Esta é a mesma análise que o PHP aplica a $_GET e $_POST, razão pela qual um campo de formulário chamado user[name] chega como $_POST['user']['name'].

Lendo a string de consulta de uma URL

Um padrão comum é extrair a string de consulta de uma URL completa com parse_url() e depois passá-la para parse_str():

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

Saída:

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

Para a string de consulta da requisição atual, normalmente não é necessário usar parse_str() — o PHP já preencheu $_GET. Use parse_str() quando a string de consulta vier de outro lugar: uma URL armazenada, uma resposta de API ou um payload de webhook.

Nota de segurança

Quando o segundo argumento é o array de resultado (conforme mostrado acima), parse_str() é segura e previsível. O perigo existia apenas com a forma de argumento único, agora removida, que injetava variáveis diretamente no escopo local — entradas não confiáveis podiam sobrescrever variáveis existentes (uma variante do antigo problema register_globals). Como o PHP 8.0 removeu essa forma, esse risco foi eliminado no código moderno, mas você ainda deve tratar qualquer valor proveniente de uma string de consulta como entrada não confiável do usuário e validá-lo antes de usá-lo.

Funções relacionadas

• explode() — divide uma string por um delimitador quando você precisa de uma lista simples em vez de análise de key=value.
• implode() — une elementos de array de volta em uma string.
• str_getcsv() — analisa strings no formato CSV em arrays.
• Manipulação de formulários PHP — como $_GET e $_POST usam essa mesma análise.

Prática