(PHP 4, PHP 5, PHP 7, PHP 8)
list — Assign variables as if they were an array
Like array(), this is not really a function, but a language construct. list() is used to assign a list of variables in one operation. Strings can not be unpacked and list() expressions can not be completely empty.
Note:
Before PHP 7.1.0, list() only worked on numerical arrays and assumes the numerical indices start at 0.
var
A variable.
vars
Further variables.
Returns the assigned array.
Version | Description |
---|---|
7.3.0 | Support for reference assignments in array destructuring was added. |
7.1.0 | It is now possible to specify keys in list(). This enables destructuring of arrays with non-integer or non-sequential keys. |
Example #1 list() examples
<?php$info = array('coffee', 'brown', 'caffeine');// Listing all the variableslist($drink, $color, $power) = $info;echo "$drink is $color and $power makes it special.\n";// Listing some of themlist($drink, , $power) = $info;echo "$drink has $power.\n";// Or let's skip to only the third onelist( , , $power) = $info;echo "I need $power!\n";// list() doesn't work with stringslist($bar) = "abcde";var_dump($bar); // NULL?>
Example #2 An example use of list()
<?php$result = $pdo->query("SELECT id, name FROM employees");while (list($id, $name) = $result->fetch(PDO::FETCH_NUM)) { echo "id: $id, name: $name\n";}?>
Example #3 Using nested list()
<?phplist($a, list($b, $c)) = array(1, array(2, 3));var_dump($a, $b, $c);?>
int(1) int(2) int(3)
Example #4 list() and order of index definitions
The order in which the indices of the array to be consumed by list() are defined is irrelevant.
<?php$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');$foo[1] = 'd';list($x, $y, $z) = $foo;var_dump($foo, $x, $y, $z);
Gives the following output (note the order of the elements compared in which order they were written in the list() syntax):
array(4) { [2]=> string(1) "a" ["foo"]=> string(1) "b" [0]=> string(1) "c" [1]=> string(1) "d" } string(1) "c" string(1) "d" string(1) "a"
Example #5 list() with keys
As of PHP 7.1.0 list() can now also contain explicit keys, which can be given as arbitrary expressions. Mixing of integer and string keys is allowed; however, elements with and without keys cannot be mixed.
<?php$data = [ ["id" => 1, "name" => 'Tom'], ["id" => 2, "name" => 'Fred'],];foreach ($data as ["id" => $id, "name" => $name]) { echo "id: $id, name: $name\n";}echo PHP_EOL;list(1 => $second, 3 => $fourth) = [1, 2, 3, 4];echo "$second, $fourth\n";
The above example will output:
id: 1, name: Tom id: 2, name: Fred 2, 4