list()

Introdução

list() é uma construção de linguagem PHP (não uma função) que desestrutura um array, atribuindo cada um dos seus elementos a uma variável separada em um único comando. Em vez de extrair valores índice por índice, você descreve a estrutura do array no lado esquerdo e deixa o PHP preencher as variáveis.

Esta página aborda a sintaxe básica, a forma abreviada moderna [], como ignorar e aninhar elementos, a forma com chaves associativas (PHP 7.1+) e os erros comuns a observar. list() é mais útil quando uma função ou expressão já retorna um array PHP e você quer nomear suas partes.

Sintaxe Básica

A sintaxe básica da construção list() é a seguinte:

A sintaxe PHP do list()

list($var1, $var2, $var3) = $array;

O $array no lado direito fornece os valores. A construção os atribui às variáveis da esquerda por posição — o elemento 0 vai para $var1, o elemento 1 para $var2, e assim por diante.

Sintaxe abreviada de array []

A partir do PHP 7.1, você pode usar colchetes no lugar da palavra-chave list(). As duas formas são equivalentes — a forma abreviada é agora o estilo mais comum:

<?php

$point = [10, 20];

[$x, $y] = $point;   // same as list($x, $y) = $point;

echo "$x, $y"; // Output: 10, 20

Exemplo de Uso

Veja um exemplo de como a construção list() pode ser usada em PHP:

Exemplo do list() em PHP

Neste exemplo, a construção list() atribui os valores do array $fruits às variáveis $fruit1, $fruit2 e $fruit3. O valor de cada variável é então exibido na tela.

Ignorando Elementos

Você pode ignorar valores que não precisa deixando o slot correspondente vazio. Apenas os elementos nomeados são atribuídos:

<?php

$data = ['red', 'green', 'blue', 'yellow'];

// Grab only the third element; skip the rest
list(, , $third) = $data;

echo $third; // Output: blue

As duas vírgulas iniciais ignoram os elementos 0 e 1, então $third recebe o elemento 2 ("blue").

Desestruturação Aninhada

list() pode ser aninhado para desempacotar arrays multidimensionais. A estrutura no lado esquerdo deve espelhar a estrutura do array no lado direito:

<?php

$coords = [[1, 2], [3, 4]];

[[$x1, $y1], [$x2, $y2]] = $coords;

echo "$x1,$y1 $x2,$y2"; // Output: 1,2 3,4

Trocando Variáveis

Como o lado direito é totalmente avaliado antes da atribuição, list() é uma forma elegante de trocar duas variáveis sem precisar de uma temporária:

<?php

$a = 'first';
$b = 'second';

[$a, $b] = [$b, $a];

echo "$a $b"; // Output: second first

Uso Avançado

A construção list() também pode ser combinada com outras funções PHP para tarefas mais complexas. Por exemplo, funciona bem com explode() para dividir uma string em um array:

Neste exemplo, explode() divide a variável $string em um array. A construção list() então atribui os valores do array a $fruit1, $fruit2 e $fruit3. O valor de cada variável é então exibido na tela.

Além disso, list() suporta arrays associativos associando chaves a variáveis:

<?php

$person = ['name' => 'Alice', 'age' => 30, 'city' => 'New York'];
list('name' => $name, 'age' => $age) = $person;

echo $name; // Output: Alice
echo $age;  // Output: 30

Note que a forma associativa exige que cada variável especifique sua chave — não é possível misturar entradas com chave e posicionais no mesmo list(). Essa forma é especialmente útil ao trabalhar com dados estruturados como respostas JSON ou linhas de banco de dados.

Desestruturação em um Loop foreach

list() (ou []) pode ser usado diretamente na posição de valor de um loop foreach, desempacotando cada linha durante a iteração. Esse é um padrão comum para arrays de pares ou registros:

<?php

$people = [
    ['Alice', 30],
    ['Bob', 25],
];

foreach ($people as [$name, $age]) {
    echo "$name is $age\n";
}
// Output:
// Alice is 30
// Bob is 25

Erros Comuns

• list() funciona apenas com arrays. Passar uma string ou null não os desestrutura caractere por caractere; as variáveis simplesmente recebem null (com um aviso no caso de null).
• Elementos ausentes resultam em null. Se o array tiver menos elementos do que variáveis, as variáveis extras se tornam null e o PHP emite um aviso Undefined array key. Certifique-se de que o array seja grande o suficiente, ou use um valor padrão com o operador de coalescência nula previamente.
• A ordem de atribuição não é garantida. Não dependa de qual variável é atribuída primeiro dentro de um único list(); nunca escreva código onde um alvo depende de outro ser atribuído antes no mesmo comando.
• Não é possível misturar entradas com e sem chave. Em um único list(), ou todas as entradas usam 'chave' => $var ou nenhuma usa.

Boas Práticas

• Use para nomear partes de arrays, não para construí-los. list() lê de um array; nunca cria um. Use array() / [] quando precisar construir dados.
• Use nomes de variáveis significativos. [$id, $name, $email] = $row; documenta a estrutura de $row muito melhor do que $row[0], $row[1], $row[2] espalhados pelo código.
• Prefira a sintaxe abreviada [] no PHP 7.1+ para consistência com os literais de array que você já escreve.
• Use a forma com chave para dados associativos para não depender silenciosamente da ordem de inserção.

Conclusão

A construção list() (e seu equivalente moderno []) permite desestruturar um array em variáveis nomeadas em um único comando expressivo — por posição, por chave, aninhado ou dentro de um foreach. Use-a para dar nomes significativos às partes de arrays retornados por funções como explode(), e tenha os erros acima em mente para que valores ausentes ou com erros de digitação não o surpreendam.

Prática