list
(PHP 4, PHP 5, PHP 7, PHP 8)
list — Assign variables as if they were an array
Description
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.
Parameters
-
var -
A variable.
-
vars -
Further variables.
Return Values
Returns the assigned array.
Changelog
| 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. |
Examples
Example #1 list() examples
<?php
$info = array('coffee', 'brown', 'caffeine');
// Listing all the variables
list($drink, $color, $power) = $info;
echo "$drink is $color and $power makes it special.\n";
// Listing some of them
list($drink, , $power) = $info;
echo "$drink has $power.\n";
// Or let's skip to only the third one
list( , , $power) = $info;
echo "I need $power!\n";
// list() doesn't work with strings
list($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()
<?php
list($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
