list

Assign variables as if they were an array

&reftitle.description; `array` `list` `mixed` `var` `mixed` `vars`

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.

Before PHP 7.1.0, `list` only worked on numerical arrays and assumes the numerical indices start at 0.

&reftitle.parameters;

`var`

- A variable.

`vars`

- Further variables.

&reftitle.returnvalues;

Returns the assigned array.

&reftitle.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.

&reftitle.examples;

### `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
    ?>

### 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";
    }
    ?>

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

### `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"

### `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";

&example.outputs;

    id: 1, name: Tom
    id: 2, name: Fred

    2, 4

&reftitle.seealso;

- `each`
- `array`
- `extract`