PHP list() e desestruturação de arrays: [$a, $b] = $arr

[$a, $b] = $array; separa os elementos de um array em variáveis numa linha: $a recebe $array[0], $b recebe $array[1]. list($a, $b) = $array; é a grafia antiga da mesma coisa, e ['name' => $name] = $user; faz isso pela chave.

<?php
$point = [3, 7];
[$x, $y] = $point;
echo "x = $x, y = $y\n";

// Same thing with list()
list($x, $y) = $point;
echo "x = $x, y = $y\n";

// Very common with explode()
[$user, $domain] = explode('@', 'ada@example.com');
echo "User: $user, domain: $domain\n";

Combinar desestruturação com explode() é o uso clássico: divida uma string, dê nome às partes e siga em frente.

Pular elementos

Deixe uma posição vazia para pulá-la. Você também pode parar antes: elementos não usados no fim são ignorados.

<?php
$row = ['2026-03-14', 'Ada', 'Lovelace', 'admin', 'active'];

[, $first, $last] = $row;            // skip the date, ignore the rest
echo "$first $last\n";

[$date, , , $role] = $row;           // skip two in the middle
echo "$date: $role\n";

// Only the time part of a timestamp string
[, $time] = explode(' ', '2026-03-14 09:30:00');
echo "Time: $time\n";

Desestruturar um array associativo pela chave

Com chaves, a ordem no array não importa e você pega só os campos de que precisa. A chave vem antes de =>, a variável depois.

<?php
$user = ['id' => 7, 'name' => 'Grace', 'email' => 'grace@example.com', 'age' => 45];

['name' => $name, 'email' => $email] = $user;
echo "$name <$email>\n";

// Rename while you extract
['id' => $userId] = $user;
echo "User #$userId\n";

// Keys can be expressions
$field = 'age';
[$field => $value] = $user;
echo "$field: $value\n";

// Nested: reach inside a nested array
$order = ['id' => 5, 'customer' => ['name' => 'Ada', 'country' => 'UK']];
['id' => $id, 'customer' => ['country' => $country]] = $order;
echo "Order $id ships to $country\n";

Os padrões se aninham do mesmo jeito para listas: [[$x1, $y1], [$x2, $y2]] = $line; lê dois pontos de uma vez. Desde o PHP 7.3, uma variável num padrão também pode ser uma referência, [, &$second] = $counts;, então alterar $second altera o array.

Uma atribuição usa posições ou chaves, nunca as duas. [$a, 'k' => $b] = $arr; para com Cannot mix keyed and unkeyed array entries in assignments.

Trocar duas variáveis

Monte um array com os dois valores na ordem inversa e desestruture de volta. Sem variável temporária.

<?php
$a = 'left';
$b = 'right';

[$a, $b] = [$b, $a];
echo "$a $b\n";

// Rotate three values
$x = 1; $y = 2; $z = 3;
[$x, $y, $z] = [$y, $z, $x];
echo "$x $y $z\n";

Retornar vários valores de uma função

Uma função PHP retorna um valor, mas esse valor pode ser um array. Desestruturar na chamada faz parecer que são vários valores de retorno. Para mais de dois ou três valores, retorne chaves para que quem chama não confunda a ordem.

<?php
function minMax(array $numbers): array
{
    return [min($numbers), max($numbers)];
}

[$low, $high] = minMax([4, 9, 1, 7]);
echo "Range: $low to $high\n";

function parseName(string $full): array
{
    $parts = explode(' ', $full, 2);
    return ['first' => $parts[0], 'last' => $parts[1] ?? ''];
}

['last' => $last, 'first' => $first] = parseName('Ada Lovelace');
echo "$last, $first\n";

Desestruturação no foreach

A mesma sintaxe funciona na linha do foreach, então cada linha já chega separada em variáveis com nome. É isso que as pessoas chamam de "foreach com list()". Mais padrões de loop estão na página sobre foreach.

<?php
$routes = [
    ['GET', '/users', 'listUsers'],
    ['POST', '/users', 'createUser'],
    ['GET', '/users/{id}', 'showUser'],
];

foreach ($routes as [$method, $path, $handler]) {
    printf("%-5s %-12s -> %s()\n", $method, $path, $handler);
}

$people = [
    ['name' => 'Ada', 'city' => 'London'],
    ['name' => 'Linus', 'city' => 'Helsinki'],
];

foreach ($people as ['name' => $name, 'city' => $city]) {
    echo "$name lives in $city\n";
}

O operador spread (...)

Os três pontos desempacotam um array no lugar. Num literal de array, [...$a, ...$b] junta arrays. Numa chamada de função, f(...$args) passa os elementos como argumentos separados. Na definição de uma função, ...$args reúne os argumentos extras num array.

<?php
$fruits = ['apple', 'pear'];
$veg = ['carrot'];
$all = [...$fruits, ...$veg, 'bread'];
print_r($all);

// String keys too (PHP 8.1): later keys win, like array_merge
$defaults = ['color' => 'blue', 'size' => 'M'];
$custom = ['size' => 'L'];
print_r([...$defaults, ...$custom]);

// Unpack into function arguments
$numbers = [4, 9, 1];
echo max(...$numbers), "\n";

// Collect any number of arguments
function total(float ...$amounts): float
{
    return array_sum($amounts);
}
echo total(1.5, 2.5, 6), "\n";

Antes do PHP 8.1, espalhar um array com chaves string era erro; agora as chaves string são mantidas e as numéricas renumeradas, com as mesmas regras do array_merge(). Parâmetros variádicos como ...$amounts são explicados junto com os outros tipos de parâmetro na página sobre funções.

Erro comum: menos elementos que variáveis

Se o array for menor que o padrão, as variáveis que faltam viram null e o PHP imprime um aviso para cada uma. Isso acontece com entrada que você não controla, como uma linha com campos faltando. Para [$name, $city, $country] = explode(',', 'Grace'); o PHP imprime:

Warning: Undefined array key 1 in /var/www/html/import.php on line 5

Warning: Undefined array key 2 in /var/www/html/import.php on line 5

Decida o que uma parte ausente deve ser e complete o array antes de desestruturar:

<?php
$lines = ['Ada,London,UK', 'Linus,Helsinki', 'Grace'];

foreach ($lines as $line) {
    [$name, $city, $country] = array_pad(explode(',', $line), 3, 'unknown');
    echo "$name | $city | $country\n";
}

Para padrões com chave, junte os padrões antes: ['a' => $a, 'b' => $b] = $input + ['a' => null, 'b' => null];. O operador + só adiciona as chaves que $input ainda não tem.