list

(PHP 4, PHP 5, PHP 7, PHP 8)

list配列と同様の形式で、複数の変数への代入を行う

説明

function list(mixed $var, mixed ...$vars = ?): array

array() と同様に、 この関数は実際には関数ではなく言語構造です。 list() は、 この関数は、配列や ArrayAccess を実装したオブジェクトを扱うことができます。 list() には、空の式を指定できません。

注意:

PHP 7.1.0 より前のバージョンでは、list() は数値添字の配列でのみ動作し、 また、添字は 0 から始まることを想定していました。

PHP 7.1.0 より後のバージョンでは、list() には明示的にキーを含めることができます。 これによって、数値でないキーや、連続していないキーの配列を分解できるようになっています。 配列の分解に関する詳細な情報は、 配列の分解 を参照ください。

注意:

定義されていない配列のキーにアクセスしようとすることは、 その他の未定義の変数にアクセスすることと同じです: つまり、E_WARNING (PHP 8.0.0 より前は、E_NOTICE) レベルのエラーが発生し、結果は null になります。

スカラー値を分解しようとすると、 全ての変数に null が代入されます。 ArrayAccess を実装していないオブジェクトを分解しようとすると、 致命的なエラーが発生します。

パラメータ

var

変数。

vars

残りの変数。

戻り値

代入した配列を返します。

変更履歴

バージョン 説明
8.5.0 配列でない値 (null を除く) を分解すると、 E_WARNING が発生するようになりました。
7.3.0 配列へ分割して代入する操作が、リファレンスへの代入をサポートしました。
7.1.0 キーを list() 関数で指定できるようになりました。 これによって、キーが数値でなかったり、連続していなかったりした場合に配列の構造を変えることができるようになります。

例1 list() の例

<?php

$info = array('コーヒー', '茶色', 'カフェイン');

// すべての変数の取得
list($drink, $color, $power) = $info;
echo "$drink の色は $color で、$power が含まれています。\n";

// 一部の変数の取得
list($drink, , $power) = $info;
echo "$drink には $power が含まれています。\n";

// 三番目のみの取得
list( , , $power) = $info;
echo "$power 欲しい!\n";

// list() は文字列では動作しません
list($bar) = "abcde";
var_dump($bar); // NULL
?>

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

例3 ネストした list() の使用法

<?php

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

var_dump($a, $b, $c);

?>

上の例の出力は以下となります。

int(1)
int(2)
int(3)

list() が配列の要素をどの順に処理するかは、配列の添字とは無関係です。

例4 list() と添字の定義順

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

結果は次のようになります (list() 内で要素をどの順で利用しているかに注目しましょう)。

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"

例5 list() をキーを指定して使う

PHP 7.1.0 以降では、list() に明示的に キーを含めることができるようになりました。 任意の式も指定可能です。 数値や文字のキーも許されますが、 キーがない要素とある要素を混ぜることは許されません

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

上の例の出力は以下となります。

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

2, 4

参考

  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • array() - 配列を生成する
  • extract() - 配列からシンボルテーブルに変数をインポートする

add a note

User Contributed Notes 25 notes

up
154
carlosv775 at gmail dot com
9 years 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
142
Rhamnia Mohamed
9 years 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
98
grzeniufication
11 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
9
xmgr2 at protonmail dot com
1 year ago
... and it also supports pushing items onto arrays.

I couldn't find any official documentation on this behavior, but it appears that you can "push" elements onto arrays directly using array destructuring assignments.

<?php
$users = [
    [1, 'Alice', 'alice@example.com', 'secret123'],
    [2, 'Bob', 'bob@example.com', 'pass456'],
    [3, 'Charlie', 'charlie@example.com', 'hunter678'],
];

$ids       = [];
$names     = [];
$emails    = [];
$passwords = [];

foreach ($users as $user) {
    [$ids[], $names[], $emails[], $passwords[]] = $user;
}
?>

For well-documented alternatives, consider using array_column(), which does quite the same:

<?php
$ids       = array_column($users, 0);
$names     = array_column($users, 1);
$emails    = array_column($users, 2);
$passwords = array_column($users, 3);
?>
up
77
megan at voices dot com
13 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
76
chris at chlab dot ch
13 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
52
grzeniufication
9 years 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
37
pemapmodder1970 at gmail dot com
10 years ago
list() can be used with foreach

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

foreach($array