PHP 7.0.6 Released

list

(PHP 4, PHP 5, PHP 7)

listAssign variables as if they were an array

Description

array list ( mixed $var1 [, mixed $... ] )

Like array(), this is not really a function, but a language construct. list() is used to assign a list of variables in one operation.

Parameters

var1

A variable.

Return Values

Returns the assigned array.

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()

<table>
 <tr>
  <th>Employee name</th>
  <th>Salary</th>
 </tr>

<?php
$result 
$pdo->query("SELECT id, name, salary FROM employees");
while (list(
$id$name$salary) = $result->fetch(PDO::FETCH_NUM)) {
    echo 
" <tr>\n" .
          
"  <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
          
"  <td>$salary</td>\n" .
          
" </tr>\n";
}

?>

</table>

Example #3 Using nested list()

<?php

list($a, list($b$c)) = array(1, array(23));

var_dump($a$b$c);

?>
int(1)
int(2)
int(3)

Example #4 Using list() with array indices

<?php

$info 
= array('coffee''brown''caffeine');

list(
$a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>

Gives the following output (note the order of the elements compared in which order they were written in the list() syntax):

array(3) {
  [2]=>
  string(8) "caffeine"
  [1]=>
  string(5) "brown"
  [0]=>
  string(6) "coffee"
}

Notes

Warning

In PHP 5, list() assigns the values starting with the right-most parameter. In PHP 7, list() starts with the left-most parameter.

If you are using plain variables, you don't have to worry about this. But if you are using arrays with indices you usually expect the order of the indices in the array the same you wrote in the list() from left to right, which is not the case in PHP 5, as it's assigned in the reverse order.

Generally speaking, it is advisable to avoid relying on a specific order of operation, as this may change again in the future.

Warning

Modification of the array during list() execution (e.g. using list($a, $b) = $b) results in undefined behavior.

Note:

list() only works on numerical arrays and assumes the numerical indices start at 0.

See Also

  • each() - Return the current key and value pair from an array and advance the array cursor
  • array() - Create an array
  • extract() - Import variables into the current symbol table from an array

User Contributed Notes

chris at chlab dot ch
3 years ago
The example states the following:
<?php
// list() doesn't work with strings
list($bar) = "abcde";
var_dump($bar);
// output: NULL
?>

If the string is in a variable however, it seems using list() will treat the string as an array:
<?php
$string
= "abcde";
list(
$foo) = $string;
var_dump($foo);
// output: string(1) "a"
?>
pemapmodder1970 at gmail dot com
2 months ago
list() can be used with foreach

<?php
$array
= [[1, 2], [3, 4], [5, 6]];

foreach(
$array as list($odd, $even)){
    echo
"$odd is odd; $even is even", PHP_EOL;
}
?>

The output:
===
1 is odd; 2 is even
3 is odd; 4 is even
5 is odd; 6 is even
megan at voices dot com
2 years ago
As noted, list() will give an error if the input array is too short. This can be avoided by array_merge()'ing in some default values. For example:

<?php
$parameter
= 'name';
list(
$a, $b ) = array_merge( explode( '=', $parameter ), array( true ) );
?>

However, you will have to array_merge with an array long enough to ensure there are enough elements (if $parameter is empty, the code above would still error).

An alternate approach would be to use array_pad on the array to ensure its length (if all the defaults you need to add are the same).

<?php
    $parameter
= 'bob-12345';
    list(
$name, $id, $fav_color, $age ) = array_pad( explode( '-', $parameter ), 4, '' );
   
var_dump($name, $id, $fav_color, $age);
/* outputs
string(3) "bob"
string(5) "12345"
string(0) ""
string(0) ""
*/
?>
svennd
3 years ago
The list() definition won't throw an error if your array is longer then defined list.
<?php

list($a, $b, $c) = array("a", "b", "c", "d");

var_dump($a); // a
var_dump($b); // b
var_dump($c); // c
?>
grzeniufication
1 year ago
The example showing that:

$info = array('kawa', 'brązowa', 'kofeina');
list($a[0], $a[1], $a[2]) = $info;
var_dump($a);

outputs:
array(3) {
[2]=>
string(8) "kofeina"
[1]=>
string(5) "brązowa"
[0]=>
string(6) "kawa"
}

One thing to note here is that if you define the array earlier, e.g.:
$a = [0, 0, 0];

the indexes will be kept in the correct order:

array(3) {
  [0]=>
  string(4) "kawa"
  [1]=>
  string(8) "brązowa"
  [2]=>
  string(7) "kofeina"
}

Thought that it was worth mentioning.
Colin Guthrie
9 months ago
If you want use the undefined behaviour as you might expect it e.g. if you want:

  $b = ['a','b']; list($a, $b) = $b;

to result in $a=='a' and $b=='b', then you can just cast $b to an array (even although it already is) to create a copy. e.g.

  $b = ['a','b']; list($a, $b) = (array)$b;

and get the expected results.
john at jbwalker dot com
2 years ago
The list construct seems to look for a sequential list of indexes rather taking elements in sequence. What that obscure statement means is that if you unset an element, list will not simply jump to the next element and assign that to the variable but will treat the missing element as a null or empty variable:

    $test = array("a","b","c","d");
    unset($test[1]);
    list($a,$b,$c)=$test;
    print "\$a='$a' \$b='$b' \$c='$c'<BR>";

results in:
$a='a' $b='' $c='c'

not:
$a='a' $b='c' $c='d'
vickyssj7 at gmail dot com
1 year ago
if we assign array's each value individual key('numeric only'), and use the array indices in list(),, then it output the reverse order of array keys--
BUT THE HIGHER KEY VALUE ("2" in this e.g below) WILL GET THE FIRST PLACE IN THE ARRAY IN RETURN, MEANS IT PUSHES THE VALUE WITH HIGHER KEY IN PLACE OF FIRST KEY VALUE, so it also gives higher key value the first priority while reversing the order of the keys and replacing the lower key value with the higher key value.

        $value = array( 0 => 'low', 2 => 'medium', 1 => 'higher');
        list($a[2], $a[1], $a[0]) = $value;
    var_dump($a);

//Outputs:---
array(3) {
            [0] => string(6) "medium"
            [1]  => string(6) "higher"
            [2]  => string(3) "low"
}
mdessaintes at gmail dot com
11 months ago
Assignement is from right to left so this result in unexpected behavior:

<?php
$str
= ['123456', 'abcdef'];
list(
$num, $str) = $str;

var_dump($num, $str);
?>

outputs :

string 'a' (length=1)
string 'abcdef' (length=6)
edam
2 years ago
This doesn't work on associative array.  For example:

    list( $a, $b, $c ) = array( 'a' => 'a', 'b' => 'b', 'c' => 'c' );
    PHP Notice:  Undefined offset: 2 in Command line code on line 1
    PHP Notice:  Undefined offset: 1 in Command line code on line 1
    PHP Notice:  Undefined offset: 0 in Command line code on line 1
Dean
4 months ago
UNDOCUMENTED BEHAVIOR:

    list($a,$b,$c) = null;

in fact works like:

    $a = null; $b = null; $c = null;

...So correspondingly:

    list($rows[]) = null;

Will increment count($rows), just as if you had executed $rows[] = null;

Watch out for this (for example) when retrieving entire tables from a database, e.g.

    while (list($rows[]) = $mysqlresult->fetch_row());

This will leave an extra 'null' entry as the last element of $rows.
mogwai512
10 months ago
I see many people offer solutions about the flipped order of the list construct. All you have to do is this:

<?php

$info
= array('coffee', 'brown', 'caffeine');

$a = list($a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>

. . . and your info will be in the correct order. You can also just assign a new var to the list and it will still work:

<?php

$info
= array('coffee', 'brown', 'caffeine');

$b = list($a[0], $a[1], $a[2]) = $info;

var_dump($b);

?>
Matt
2 years ago
You can't type check within the list() parameters:

list ( array $var1, $var2 ) = array ( array('one','two'), 'three');

generates a parse error, unexpected 'array'.
srikanth at networthindia dot com
3 years ago
Note: list cannot assign array cast of object to variables straight away. first you need to convert the object to numeric indexed array.

ex:
list($a, $b, $d) = (array) $abc; // $abc is an object; this will not assign.
list($a, $b, $c) = array_values((array) $abc); // This will work.
Arne
2 years ago
list() will give an error if the input array is too short. This can be avoided by array_merge()'ing in some default values. For example:

<?php
$parameter
= 'name';
list(
$a, $b ) = array_merge( explode( '=', $parameter ), array( true ) );
?>
Achilles at thegreatwarrior dot com
2 years ago
Second, when you’re using the list() function, you must acknowledge each array element. You could not do this
list($weekday, $month) = $date;

But you can use empty values to ignore elements:
list ($weekday, , $month) = $date;
Thanos K.
2 years ago
Also it seems that it doesn't work as expected with arrays with non numeric keys:

list($k, $l, $m) = array('a' => 'val1', 'b' => 'val2', 'c' => 'val3');

Gives empty variables..
To Top