Array Destructuring & Spread

Destructuring lets you pull multiple values out of an array into separate variables in a single statement, instead of indexing into the array field by field. The spread operator does roughly the opposite job: it expands an array's elements back out, whether into a new array literal or into a function's argument list. Together they remove a lot of the boilerplate around building and unpacking arrays.

list() and the short [$a, $b] syntax

The original way to destructure in PHP is the list() construct. Since PHP 7.1, the short array syntax [$a, $b] = $arr does the same thing and is now the more common style, mirroring how you would already write an array literal.

list() versus the short syntax

PHP

<?php
$coordinates = [10, 20];

list($x, $y) = $coordinates; // classic form
echo "{$x}, {$y}\n";

[$x, $y] = $coordinates;     // short form, same result
echo "{$x}, {$y}\n";

10, 20
10, 20

Skipping elements

You can leave a gap in the pattern to skip an element you do not need, by leaving that position empty between the commas.

Skipping the middle value

PHP

<?php
$row = ["Priya", 34, "Toronto"];

[$name, , $city] = $row; // skip the age
echo "{$name} lives in {$city}"; // Priya lives in Toronto

Priya lives in Toronto

Keyed destructuring

When the source array is associative, you can destructure by key instead of by position - this is often clearer than positional destructuring because it does not depend on the order fields appear in, only on their names.

Destructuring by key

PHP

<?php
$user = ["id" => 7, "name" => "Femi", "role" => "editor"];

["name" => $name, "role" => $role] = $user;
echo "{$name} is a(n) {$role}"; // Femi is a(n) editor

Femi is a(n) editor

Keyed destructuring also works naturally in a foreach loop when each element of the outer array is itself an associative array - a very common shape for rows pulled from a database.

Destructuring inside a foreach

PHP

<?php
$users = [
    ["name" => "Femi", "role" => "editor"],
    ["name" => "Ravi", "role" => "admin"],
];

foreach ($users as ["name" => $name, "role" => $role]) {
    echo "{$name}: {$role}\n";
}

Femi: editor
Ravi: admin

Destructuring a missing key

If you destructure a key that does not exist in the source array, PHP emits an "Undefined array key" warning and assigns `null` to that variable rather than throwing a fatal error. Validate the shape of the data first (or provide a default value with `??`) when the input might not be guaranteed to have every key.

The spread operator in array literals

The ... spread operator expands the elements of one array directly into a new array literal. It is a concise alternative to array_merge() for combining indexed arrays, and unlike array_merge(), it reads left-to-right in the exact shape of the resulting array.

Spreading indexed arrays together

PHP

<?php
$fruits = ["apple", "banana"];
$moreFruits = ["cherry", "date"];

$all = [...$fruits, ...$moreFruits, "elderberry"];
print_r($all);

Array
(
    [0] => apple
    [1] => banana
    [2] => cherry
    [3] => date
    [4] => elderberry
)

Spreading with string keys (PHP 8.1+)

Early versions of the spread operator only worked cleanly with integer-keyed arrays. As of PHP 8.1, spreading an array with string keys is fully supported, and behaves like array_merge() for those keys - a later spread with the same key overwrites an earlier one.

Spreading associative arrays

PHP

<?php
$defaults = ["theme" => "light", "retries" => 3];
$overrides = ["theme" => "dark"];

$settings = [...$defaults, ...$overrides];
print_r($settings); // "theme" from $overrides wins - later spread wins

Array
(
    [theme] => dark
    [retries] => 3
)

Spreading into function calls

The same ... syntax unpacks an array into a function's positional arguments, which is especially handy when the values you need to pass are already sitting in an array - for example, values collected from user input or built up in a loop.

Unpacking arguments with spread

PHP

<?php
function add(int $a, int $b, int $c): int {
    return $a + $b + $c;
}

$numbers = [3, 4, 5];
echo add(...$numbers); // 12 - same as add(3, 4, 5)

list() and [$a, $b] = $arr are interchangeable - the short form is simply the modern convention.
Destructuring more variables than the array has elements assigns null (with a warning) to the extras, rather than raising a fatal error.
Spread in an array literal always creates a shallow copy of the source elements - nested arrays inside are still copied by value, same as any PHP array assignment.
Spread works with any iterable, not just plain arrays, which includes generators and objects implementing Traversable.

Spread versus array_merge()

For plain indexed arrays, `[...$a, ...$b]` and `array_merge($a, $b)` produce the same result. The spread form tends to read more clearly when you are combining several arrays with extra literal values mixed in, as in the fruits example above.

Tip

Favor keyed destructuring (`["key" => $var] = $arr`) over positional destructuring whenever the source is associative - it keeps working correctly even if the array's field order changes later, which positional destructuring is silently sensitive to.