list

(PHP 4, PHP 5, PHP 7)

listWeist Variablen zu, als wären sie ein Array

Beschreibung

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

Wie array() ist auch dies keine wirkliche Funktion, sondern ein Sprachkonstrukt. list() wird verwendet, um eine Liste von Variablen mit einer Operation zuzuweisen.

Hinweis:

Vor PHP 7.1.0 funktionierte list() nur bei numerischen Arrays und basierte auf der Annahme, dass die numerischen Indizes bei 0 beginnen.

Warnung

In PHP 5 weist list() die Werte von rechts beginnend zu. In PHP 7 beginnt list() von links.

Wenn Sie einfache Variablen benutzen, brauchen Sie sich nicht darum zu kümmern. Wenn Sie jedoch Arrays mit Indizes verwenden, erwarten Sie gewöhnlich die Reihenfolge der Indizes in dem Array genau so, wie Sie sie in list() geschrieben haben (von links nach rechts), was jedoch in PHP 5 nicht der Fall ist. Es wird in der umgekehrten Reihenfolge zugewiesen.

Allgemein gesagt, ist es ratsam sich nicht auf eine bestimmte Operations-Reihenfolge zu verlassen, da sich diese zukünftig wieder ändern könnte.

Warnung

Die Veränderung des Array während der Ausführung von list() (z.B. durch list($a, $b) = $b), hat undefiniertes Verhalten zur Folge.

Parameter-Liste

var1

Eine Variable.

Rückgabewerte

Gibt das zugewiesene Array zurück.

Changelog

Version Beschreibung
7.1.0 Es ist nun möglich Schlüssel in list() anzugeben. Dies ermöglicht die Destrukturierung von Arrays mit nicht numerischen oder nicht fortlaufenden Schlüsseln.
7.0.0 Die Reihenfolge, in der die Zuweisungsoperationen durchgeführt werden, wurde geändert.
7.0.0 list() Ausdrücke dürfen nicht mehr vollständig leer sein.
7.0.0 Zeichenketten können nicht mehr entpackt werden.

Beispiele

Beispiel #1 list() Beispiele

<?php

$info 
= array('Kaffee''braun''Koffein');

// Auflisten aller Variablen
list($drink$color$power) = $info;
echo 
"$drink ist $color und $power macht es zu etwas besonderem.\n";

// Ein paar davon auflisten
list($drink, , $power) = $info;
echo 
"$drink hat $power.\n";

// Oder nur die dritte ausgeben
list( , , $power) = $info;
echo 
"Ich brauche $power!\n";

// list() funktioniert nicht mit Zeichenketten
list($bar) = "abcde";
var_dump($bar); // NULL
?>

Beispiel #2 Eine Beispielverwendung von list()

<table>
 <tr>
  <th>Mitarbeitername</th>
  <th>Gehalt</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>

Beispiel #3 Verschachtelte list() verwenden

<?php

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

var_dump($a$b$c);

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

Beispiel #4 list() mit Array Indizes verwenden

<?php

$info 
= array('Kaffee''braun''Koffein');

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

var_dump($a);

?>

Erzeugt folgende Ausgabe (beachten Sie die Reihenfolge der Elemente verglichen mit der in list() eingetragenen Reihenfolge):

Das oben gezeigte Beispiel erzeugt folgende Ausgabe mit PHP 7:

array(3) {
  [0]=>
  string(6) "Kaffee"
  [1]=>
  string(5) "braun"
  [2]=>
  string(7) "Koffein"
}

Das oben gezeigte Beispiel erzeugt folgende Ausgabe mit PHP 5:

array(3) {
  [2]=>
  string(7) "Koffein"
  [1]=>
  string(5) "braun"
  [0]=>
  string(6) "Kaffee"
}

Beispiel #5 list() und die Reihenfolge der Index-Definitionen

Die Reihenfolge, in der die Indizes des von list() zu konsumierenden Arrays definiert wurden, ist irrelevant.

<?php
$foo 
= array(=> 'a''foo' => 'b'=> 'c');
$foo[1] = 'd';
list(
$x$y$z) = $foo;
var_dump($foo$x$y$z);

Erzeugt folgende Ausgabe (beachten Sie die Reihenfolge der Elemente verglichen mit der in list() eingetragenen Reihenfolge):

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"

Beispiel #6 list() mit Schlüsseln

Von PHP 7.1.0 an kann list() nun ebenfalls explizite Schlüssel enthalten, die als beliebige Ausdrücke angegeben werden können. Die Kombination von Integer- und Zeichenkettenschlüsseln ist erlaubt; allerdings dürfen Elemente mit und ohne Schlüssel nicht kombiniert werden.

<?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(
=> $second=> $fourth) = [1234];
echo 
"$second$fourth\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

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

2, 4

Siehe auch

  • each() - Liefert das aktuelle Paar (Schlüssel und Wert) eines Arrays und rückt den Arrayzeiger vor
  • array() - Erstellt ein Array
  • extract() - Importiert Variablen eines Arrays in die aktuelle Symboltabelle

add a note add a note

User Contributed Notes 16 notes

up
65
Rhamnia Mohamed
1 year ago
Since PHP 7.1, keys can be specified

exemple :
<?php
$array
= ['locality' => 'Tunis', 'postal_code' => '1110'];

list(
'postal_code' => $zipCode, 'locality' => $locality) = $array;

print
$zipCode; // will output 1110
print $locality; // will output Tunis
?>
up
68
grzeniufication
4 years 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.
up
49
grzeniufication
1 year ago
<?php
/**
* It seems you can skip listed values.
* Here's an example to show what I mean.
*
* FYI works just as well with PHP 7.1 shorthand list syntax.
* Tested against PHP 5.6.30, 7.1.5
*/
$a = [ 1, 2, 3, 4 ];

// this is quite normal use case for list
echo "Unpack all values\n";
list(
$v1, $v2, $v3, $v4) = $a;
echo
"$v1, $v2, $v3, $v4\n";
unset(
$v1, $v2, $v3, $v4);

// this is what I mean:
echo "Skip middle\n";
list(
$v1, , , $v4) = $a;
echo
"$v1, $v2, $v3, $v4\n";
unset(
$v1, $v2, $v3, $v4);

echo
"Skip beginning\n";
list( , ,
$v3, $v4) = $a;
echo
"$v1, $v2, $v3, $v4\n";
unset(
$v1, $v2, $v3, $v4);

echo
"Skip end\n";
list(
$v1, $v2, , ) = $a;
echo
"$v1, $v2, $v3, $v4\n";
unset(
$v1, $v2, $v3, $v4);

echo
"Leave middle\n";
list( ,
$v2, $v3, ) = $a;
echo
"$v1, $v2, $v3, $v4\n";
unset(
$v1, $v2, $v3, $v4);
up
69
chris at chlab dot ch
5 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"
?>
up
55
megan at voices dot com
5 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) ""
*/
?>
up
28
carlosv775 at gmail dot com
1 year ago
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'];
?>
up
46
svennd
5 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
?>
up
26
pemapmodder1970 at gmail dot com
2 years 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
up
2
contato at tobias dot ws
6 months ago
Since PHP 7.1 the [] may now be used as an alternative to the existing list() syntax:

<?php
[$number, $message] = explode('|', '123|Hello World!');
?>
up
15
john at jbwalker dot com
4 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'
up
2
blazej
1 year ago
From PHP Version 7.1 you can specify keys in list(), or its new shorthand [] syntax. This enables destructuring of arrays with non-integer or non-sequential keys.

<?php
$data
= [
    [
"id" => 1, "name" => 'Tom'],
    [
"id" => 2, "name" => 'Fred'],
];

// list() style
list("id" => $id1, "name" => $name1) = $data[0];

// [] style
["id" => $id1, "name" => $name1] = $data[0];

// list() style
foreach ($data as list("id" => $id, "name" => $name)) {
   
// logic here with $id and $name
}

// [] style
foreach ($data as ["id" => $id, "name" => $name]) {
   
// logic here with $id and $name
}
up
3
anthony dot ossent at live dot fr
1 year ago
a simple example of use to swap two variables :

$a = 'hello';
$b = 'world';

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

echo $a . ' ' . $b; //display "world hello"

another example :

function getPosition($x, $y, $z)
{
   // ... some operations like $x++...
   return [$x, $y, $z];
}

list($x, $y, $z) = getPosition($x ,$y, $z);
up
4
Colin Guthrie
3 years 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.
up
4
Dean
2 years 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.
up
2
Mardaneus
3 months ago
Unless you specify keys when using list() it expects the array being fed into it to start at 0.

So having the following code will result in a notice level warning "Undefined offset: 0" and variables not filling as expected

<?php
list($c1, $c2, $c3) = array [1 =>'a', 2 => 'b', 3 => 'c'];

var_dump($c1); // NULL
var_dump($c2); // string(1) "a"
var_dump($c3); // string(1) "b"

?>
up
0
petru at fuxspam dot xtremeweb dot ro
6 months ago
This is something I haven't seen in documentation.

Since PHP 7.1, you can use short-hand list unpacking using square brackets, just like short-hand array declaration:

<?php

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

// short-hand array definition
[$a, $b, $c] = $foo;
echo
$a; // displays "a"

// it's same like:
list($x, $y, $z) = $foo;
echo
$x; // displays "a"

?>
To Top