list

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

list — Присваивает переменным значения как массиву

Описание

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

Как и конструкция array(), это не функция, а языковая конструкция. Конструкция list() присваивает списку переменных значения за одну операцию. Распаковку поддерживают только массивы и объекты, классы которых реализуют интерфейс ArrayAccess. Нельзя указывать пустую конструкцию list() в выражениях присваивания.

Замечание:
До PHP 7.1.0 конструкция list() работала только с индексными массивами и принимала числовые индексы начиная с 0.

Начиная с PHP 7.1.0 для деструктуризации массивов с нецелочисленными или непоследовательными ключами в конструкции list() разрешили указывать явные ключи. Подробнее об этом рассказывает блок «Деструктуризация массива».

Замечание:
Попытка получить доступ к неопределённому ключу массива аналогична обращению к любой другой неопределённой переменной: выдаётся сообщение об ошибке уровня E_WARNING, или ошибки уровня E_NOTICE до PHP 8.0.0, а результатом становится значение null.

Попытка распаковать скалярное значение присваивает значение null каждой переменной в левой части выражения присваивания. При попытке распаковать объект, класс которого не реализует интерфейс ArrayAccess, возникает фатальная ошибка.

Список параметров

var: Переменная.

vars: Остальные переменные.

Возвращаемые значения

Функция возвращает массив переменных, которым присвоила значения.

Список изменений

Версия Описание

7.3.0 Добавили поддержку присваивания по ссылкам при деструктуризации массива.

7.1.0 Конструкция list() теперь поддерживает ключи. Это помогает разыменовывать ассоциативные массивы и массивы с индексами не по порядку.

Версия	Описание
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() - Переводит элементы массива в переменные текущей таблицы символов