Como passar array em query string: guia completo em PHP

Por que passar um array na URL? E por que não é tão simples quanto parece?

Imagine: você está criando em PHP um filtro de produtos para uma loja virtual. O usuário seleciona várias categorias, várias cores e uma faixa de preço. Como enviar todos esses dados para o servidor via GET? A solução óbvia seria ?categoria=1&categoria=2&categoria=3. Mas o servidor vai enxergar apenas o último valor, a menos que você use um truque.

No Stack Overflow, a pergunta "How to pass an array within a query string?" já acumulou dezenas de milhares de visualizações. Desenvolvedores tropeçam nisso todos os dias. Hoje vamos dissecar esse tópico do início ao fim: mostrar como passar um array corretamente pela URL, como processá-lo no servidor e quais armadilhas esperar.

Pronto para transformar parâmetros GET bagunçados em uma estrutura de dados organizada? Vamos nessa!

Fundamentos: como o PHP processa a query string

Quando você envia uma requisição GET, o PHP preenche automaticamente o superglobal $_GET. Se a URL contém ?nome=Joao&idade=30, o $_GET ficará assim:

array(2) {\n  ["nome"] => string(4) "Joao"\n  ["idade"] => string(2) "30"\n}

Mas e se tentarmos passar vários valores com a mesma chave? Vamos usar a URL: ?cor=vermelho&cor=verde&cor=azul. O servidor receberá apenas cor=azul. Os outros valores serão sobrescritos, porque o PHP não sabe o que fazer com chaves duplicadas.

É aqui que entra a sintaxe de colchetes, criada exatamente para resolver esse problema.

Método #1: sintaxe de colchetes (o mais popular)

Adicione colchetes ao nome do parâmetro: cor[]. Quando o PHP vê esse padrão, ele cria automaticamente um array. Exemplo de URL:

?cor[]=vermelho&cor[]=verde&cor[]=azul

No servidor, o $_GET conterá:

array(1) {\n  ["cor"] => array(3) {\n    [0] => string(8) "vermelho"\n    [1] => string(5) "verde"\n    [2] => string(4) "azul"\n  }\n}

Agora, um exemplo de código PHP que processa isso:

<?php\n// URL: exemplo.com?cor[]=vermelho&cor[]=verde&cor[]=azul\nif (isset($_GET['cor']) && is_array($_GET['cor'])) {\n    echo "Cores selecionadas:<br>";\n    foreach ($_GET['cor'] as $indice => $cor) {\n        echo ($indice + 1) . ". " . htmlspecialchars($cor) . "<br>";\n    }\n}\n?>

Resultado no navegador:

Cores selecionadas:\n1. vermelho\n2. verde\n3. azul

Chaves nomeadas: quando a ordem não importa

Às vezes, você precisa passar um array associativo (chave → valor). Para isso, use a sintaxe chave[] especificando a chave:

?filtro[categoria]=livros&filtro[preco]=100&filtro[em_estoque]=1

O PHP transformará isso em:

array(1) {\n  ["filtro"] => array(3) {\n    ["categoria"] => string(6) "livros"\n    ["preco"] => string(3) "100"\n    ["em_estoque"] => string(1) "1"\n  }\n}

Processamento no servidor:

<?php\nif (isset($_GET['filtro'])) {\n    $filtro = $_GET['filtro'];\n    $query = "SELECT * FROM produtos WHERE 1=1";\n    if (!empty($filtro['categoria'])) {\n        $query .= " AND categoria = '" . mysqli_real_escape_string($conn, $filtro['categoria']) . "'";\n    }\n    if (!empty($filtro['preco'])) {\n        $query .= " AND preco <= " . (int)$filtro['preco'];\n    }\n    // ... demais condições\n}\n?>

Método #2: JSON na query string (avançado)

Se o array for complexo (multinível ou aninhado), a sintaxe de colchetes pode ficar confusa. Uma alternativa é passar uma string JSON codificada para URL.

Montando a URL no cliente (JavaScript):

const dados = {\n    cores: ['vermelho', 'verde', 'azul'],\n    tamanhos: ['P', 'M', 'G'],\n    opcoes: {\n        embrulho_presente: true,