list()

Introduction

list() is a PHP language construct (not a function) that destructures an array, assigning each of its elements to a separate variable in a single statement. Instead of pulling values out one index at a time, you describe the shape of the array on the left-hand side and let PHP fill in the variables for you.

This page covers the basic syntax, the modern [] short form, how to skip and nest elements, the associative-key form (PHP 7.1+), and the common gotchas to watch for. list() is most useful when a function or expression already returns a PHP array and you want to name its parts.

Basic Syntax

The basic syntax of the list() construct is as follows:

The PHP syntax of the list()

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

The $array on the right-hand side provides the values. The construct assigns them to the variables on the left by position — element 0 goes to $var1, element 1 to $var2, and so on.

Short array syntax []

Since PHP 7.1, you can use square brackets instead of the list() keyword. The two forms are equivalent — the short form is now the more common style:

<?php

$point = [10, 20];

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

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

Example Usage

Here is an example of how the list() construct can be used in PHP:

Example of PHP list()

In this example, the list() construct assigns the values of the $fruits array to the variables $fruit1, $fruit2, and $fruit3. The output of each variable is then echoed to the screen.

Skipping Elements

You can ignore values you do not need by leaving the corresponding slot empty. Only the elements you name get assigned:

<?php

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

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

echo $third; // Output: blue

The two leading commas skip elements 0 and 1, so $third receives element 2 ("blue").

Nested Destructuring

list() can be nested to unpack multi-dimensional arrays. The structure on the left must mirror the structure of the array on the right:

<?php

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

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

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

Swapping Variables

Because the right-hand side is fully evaluated before assignment, list() is a clean way to swap two variables without a temporary one:

<?php

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

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

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

Advanced Usage

The list() construct can also be combined with other PHP functions for more complex tasks. For example, it works well with explode() to split a string into an array:

In this example, explode() splits the $string variable into an array. The list() construct then assigns the array values to $fruit1, $fruit2, and $fruit3. The output of each variable is then echoed to the screen.

Additionally, list() supports associative arrays by matching keys to variables:

<?php

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

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

Note that the associative form requires every variable to specify its key — you cannot mix keyed and positional entries in the same list(). This form is particularly useful when working with structured data like JSON responses or database rows.

Destructuring in a foreach Loop

list() (or []) can sit directly in the value position of a foreach loop, unpacking each row as you iterate. This is a common pattern for arrays of pairs or records:

<?php

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

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

Common Gotchas

• list() only works on arrays. Passing a string or null does not destructure it character-by-character; the variables are simply set to null (with a warning on null).
• Missing elements yield null. If the array has fewer elements than variables, the extra variables become null and PHP emits an Undefined array key warning. Make sure the array is large enough, or use a default with the null-coalescing operator beforehand.
• Assignment order is not guaranteed. Do not rely on which variable is assigned first within a single list(); never write code where one target depends on another being assigned earlier in the same statement.
• You cannot mix keyed and unkeyed entries. Within one list(), either every entry uses 'key' => $var or none do.

Best Practices

• Use it to name array parts, not to build arrays. list() reads from an array; it never creates one. Reach for array() / [] when you need to construct data.
• Use meaningful variable names. [$id, $name, $email] = $row; documents the shape of $row far better than $row[0], $row[1], $row[2] scattered through your code.
• Prefer the short [] syntax in PHP 7.1+ for consistency with the array literals you already write.
• Use the keyed form for associative data so you are not silently depending on insertion order.

Conclusion

The list() construct (and its modern [] equivalent) lets you destructure an array into named variables in one expressive statement — by position, by key, nested, or inside a foreach. Use it to give meaningful names to the parts of arrays returned by functions like explode(), and keep the gotchas above in mind so missing or mistyped values do not surprise you.

Practice