list

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

listAsigna variables como si fueran un array

Descripción

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

Al igual que array(), list() no es una función real, sino un elemento del lenguaje, que permite reunir las variables varname, ... en forma de array, para asignarlas en una sola línea. Las cadenas de caracteres no pueden ser desestructuradas y las expresiones list() no pueden estar completamente vacías.

Nota:

Anterior a PHP 7.1.0, list() funciona únicamente en un array de índice numérico y asume que el índice numérico comienza en 0.

A partir de PHP 7.1.0, list() puede también contener claves explícitas, permitiendo así la desestructuración de arrays con claves no enteras o no secuenciales. Para más detalles sobre la desestructuración de arrays, ver la sección sobre la desestructuración de arrays.

Parámetros

var

Una variable.

vars

Variables adicionales.

Valores devueltos

Devuelve el array asignado.

Historial de cambios

Versión Descripción
7.3.0 El soporte para la asignación por referencia en la desestructuración de array ha sido añadido.
7.1.0 Es ahora posible especificar las claves en la list(). Esto permite desestructurar arrays con claves no enteras o no secuenciales.

Ejemplos

Ejemplo #1 Ejemplo con list()

<?php

$info
= array('coffee', 'brown', 'caffeine');

// Lista todas las variables
list($drink, $color, $power) = $info;
echo
"$drink is $color and $power makes it special.\n";

// Lista algunas variables
list($drink, , $power) = $info;
echo
"$drink has $power.\n";

// O bien, usemos solo el tercero
list( , , $power) = $info;
echo
"I need $power!\n";

// list() no funciona con cadenas de caracteres
list($bar) = "abcde";
var_dump($bar); // NULL
?>

Ejemplo #2 Ejemplo de uso de 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";
}
?>

Ejemplo #3 Uso de un sub-list()

<?php

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

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

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

Ejemplo #4 list() y el orden de definición de los índices

El orden en el que los índices de un array a tratar por list() son definidos es irrelevante.

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

Dada la siguiente salida (note el orden de los elementos comparados y en qué orden fueron escritos en la sintaxis de la 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"

Ejemplo #5 list() con claves

A partir de PHP 7.1.0 list() puede ahora contener también claves explícitas, que pueden ser dadas como expresiones arbitrarias. La mezcla de claves int y string está permitida; Sin embargo, los elementos con y sin claves no pueden ser mezclados.

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

El resultado del ejemplo sería:

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

2, 4

Ver también

  • each() - Devuelve cada par clave/valor de un array
  • array() - Crea un array
  • extract() - Importa las variables en la tabla de símbolos