PHP list() Function

Usage — The PHP list() function is used to assign values to multiple variables as if they were an array. To put it simply, you can use this function to assign a list of variables in one operation.

It has the following syntax:

PHP

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

Here is an example of using list():

PHP

$popular = array("John", "Amanda", "Rose");
list($a, $b, $c) = $popular;

// Output — The most popular kids of my class are John, Amanda and Rose.
echo "The most popular kids of my class are $a, $b and $c.";

Return Value — This function returns the assigned array.

Additional Information — Remember that list() only works on numerical arrays and assumes the numerical indices start at 0.

I should also point out that in PHP 5, list() assigns the values starting with the right-most parameter. However, in PHP 7, list() starts with the left-most parameter. It is advisable to avoid relying on a specific order of operation, as this may change again in the future.

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

PHP Version and Changelog — The list() function is available in PHP 4, PHP 5, PHP 7. Starting from PHP 7, you can no longer unpack strings and list expressions cannot be completely empty.

Relevant Functions — Other related PHP functions that you should know about are: each() which returns the current key and value pair from an array and advance the array cursor, array() which creates an array and extract() which imports variables into the current symbol table from an array.

Go Directly To — usage, parameters, working examples or additional tips.

Parameters

var1

The var1 parameter is used to specify a variable. This is a required parameter.

You can create a list of variable number of elements to assign the array values. Just remember that only the first variable is required and rest are optional.

Working Examples

Here are some examples of using the list() function:

PHP

$people = array('Jamie', 'Tyrion', 'Arya');

list($a, $b, $c) = $people;
// Output — I like Jamie and Arya but I like Tyrion more.
echo "I like $a and $c but I like $b more.\n";

list($a, , $c) = $people;
// Output — Jamie and Arya are good fighters.
echo "$a and $c are good fighters.\n";

list( , , $c) = $people;
// Output — Arya has become a great warrior!
echo "$c has become a great warrior!\n";

list($bar) = "abcde";
// Output — NULL
var_dump($bar);

As you can see, list() doesn’t work on strings. It is also possible to skip some assignments using this function like I did in the second and third case.

The following example shows how the assignment works for nested lists:

PHP

list($a, list($b, $c)) = array(1, array(2, 3));
var_dump($a, $b, $c);
/* Output —
int(1)
int(2)
int(3) */

Here is another example showing the relationship between list() assignments and order of index definitions.

PHP

$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
$foo[1] = 'd';
list($x, $y, $z) = $foo;

print_r($foo);
/* Output —
Array
(
    [2] => a
    [foo] => b
    [0] => c
    [1] => d
) */

// Output — X: c, Y: d, Z: a
echo "X: $x, Y: $y, Z: $z";

Additional Tips

Here are some of the most upvoted tips taken from the comment section of the PHP manual:

  1. One of the examples states that list() does not work with strings. However, if the string is in a variable, it seems using list() will treat the string as an array.

    PHP

    $string = "abcde";
    list($foo) = $string;
    
    // Output — string(1) "a"
    var_dump($foo);
    

    Suggested by - chris at chlab dot ch

  2. Since PHP 7.1, keys can be specified to set values for variables. Here is an example to show it in action:

    PHP

    $array = ['locality' => 'Tunis', 'postal_code' => '1110'];
    list('postal_code' => $zipCode, 'locality' => $locality) = $array;
    
    // Output — 1110
    print $zipCode;
    
    // Output — Tunis
    print $locality;
    

    Suggested by - Rhamnia Mohamed

  3. Remember that list() will give an error if the input array is too short. This can be avoided by array_merge() in some default values. 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) "" */
    

    Suggested by - megan at voices dot com

  4. In PHP 7.1 we can do the following:

    PHP

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

    Before, we had to do:

    PHP

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

    Suggested by - carlosv775 at gmail dot com

  5. 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:

    PHP

    $test = array("a","b","c","d");
    unset($test[1]);
    list($a,$b,$c) = $test;
    
    // Output —  $a = 'a' $b = '' $c = 'c'
    print "\$a = '$a' \$b = '$b' \$c = '$c'";

    Suggested by - john at jbwalker dot com

Further Reading

  1. You can read more about the PHP list() function on PHP.net.

Reader Comments

1. You can register or login to post a comment. Asking readers to register improves the quality of discussion.

2. As a registered user, you will also get to access features like choosing between a light and dark theme or anything else that we might implement in future.

Follow Us For Updates

FacebookTwitterGoogle+
Go To Top