foreach

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

La estructura foreach proporciona una forma sencilla de iterar sobre arrays y objetos Traversable. foreach generará un error cuando se utilice con una variable que contenga un tipo de dato diferente o con una variable no inicializada.

foreach puede obtener opcionalmente la key de cada elemento: 

foreach (iterable_expression as $value) {
    statement_list
}

foreach (iterable_expression as $key => $value) {
    statement_list
}

La primera forma recorre el iterable dado por iterable_expression. En cada iteración, el valor del elemento actual se asigna a $value.

La segunda forma asignará adicionalmente la clave del elemento actual a la variable $key en cada iteración.

Tenga en cuenta que foreach no modifica el puntero interno del array, que es utilizado por funciones como current() y key().

Es posible personalizar la iteración de objetos.

Ejemplo #1 Usos comunes de foreach

<?php

echo "Solo valor\n";
$array = [1, 2, 3, 17];

foreach ($array as $value) {
    echo "Elemento actual de \$array: $value.\n";
}

echo "\n\nClave y valor:\n";
$array = [
    "one" => 1,
    "two" => 2,
    "three" => 3,
    "seventeen" => 17
];

foreach ($array as $key => $value) {
    echo "Clave: $key => Valor: $value\n";
}

echo "\n\nArrays multidimensionales clave-valor:\n";
$grid = [];
$grid[0][0] = "a";
$grid[0][1] = "b";
$grid[1][0] = "y";
$grid[1][1] = "z";

foreach ($grid as $y => $row) {
    foreach ($row as $x => $value) {
        echo "Valor en posición x=$x y y=$y: $value\n";
    }
}

echo "\n\nArrays dinámicos:\n";
foreach (range(1, 5) as $value) {
    echo "$value\n";
}

El ejemplo anterior mostrará:

Solo valor
Elemento actual de $array: 1.
Elemento actual de $array: 2.
Elemento actual de $array: 3.
Elemento actual de $array: 17.


Clave y valor:
Clave: one => Valor: 1
Clave: two => Valor: 2
Clave: three => Valor: 3
Clave: seventeen => Valor: 17


Arrays multidimensionales clave-valor:
Valor en posición x=0 y y=0: a
Valor en posición x=1 y y=0: b
Valor en posición x=0 y y=1: y
Valor en posición x=1 y y=1: z


Arrays dinámicos:
1
2
3
4
5

Nota:

foreach no admite la capacidad de suprimir mensajes de error utilizando @.

Desempaquetar arrays anidados

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Es posible iterar sobre un array de arrays y desempaquetar el array anidado en variables de bucle utilizando ya sea destructuración de arrays mediante [] o utilizando la estructura de lenguaje list() como valor.

Nota: Tenga en cuenta que destructuración de arrays mediante [] solo es posible a partir de PHP 7.1.0

En ambos ejemplos siguientes, $a se establecerá con el primer elemento del array anidado y $b contendrá el segundo elemento: 

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

foreach ($array as [$a, $b]) {
    echo "A: $a; B: $b\n";
}

foreach ($array as list($a, $b)) {
    echo "A: $a; B: $b\n";
}

El ejemplo anterior mostrará:

A: 1; B: 2
A: 3; B: 4
A: 1; B: 2
A: 3; B: 4

Cuando se proporcionan menos variables que elementos en el array, los elementos restantes serán ignorados. De manera similar, los elementos pueden omitirse utilizando una coma: 

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

foreach ($array as [$a, $b]) {
    // Note que no hay $c aquí.
    echo "$a $b\n";
}

foreach ($array as [, , $c]) {
    // Omitiendo $a y $b
    echo "$c\n";
}

El ejemplo anterior mostrará:

1 2
3 4
5
6

Se generará un aviso si no hay suficientes elementos en el array para llenar el list(): 

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

foreach ($array as [$a, $b, $c]) {
    echo "A: $a; B: $b; C: $c\n";
}

El ejemplo anterior mostrará:

Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C:

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C:

foreach y referencias

Es posible modificar directamente elementos de array dentro de un bucle precediendo $value con &. En ese caso el valor será asignado por referencia. 

<?php
$arr = [1, 2, 3, 4];
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr es ahora [2, 4, 6, 8]
var_dump($arr);
unset($value); // romper la referencia con el último elemento

El ejemplo anterior mostrará:

array(4) {
  [0]=>
  int(2)
  [1]=>
  int(4)
  [2]=>
  int(6)
  [3]=>
  &int(8)
}

Advertencia

La referencia a un $value del último elemento del array permanece incluso después del bucle foreach. Se recomienda destruir estas referencias utilizando unset(). De lo contrario, ocurrirá el siguiente comportamiento: 

<?php
$arr = [1, 2, 3, 4];
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr es ahora [2, 4, 6, 8]
var_dump($arr);

// sin un unset($value), $value sigue siendo una referencia al último elemento: $arr[3]

echo "\nOtro bucle:\n";
foreach ($arr as $key => $value) {
    // $arr[3] se actualizará con cada valor de $arr...
    echo "{$key} => {$value}\n";
}
// ...hasta que finalmente el penúltimo valor se copie sobre el último valor
var_dump($arr);

El ejemplo anterior mostrará:

array(4) {
  [0]=>
  int(2)
  [1]=>
  int(4)
  [2]=>
  int(6)
  [3]=>
  &int(8)
}

Otro bucle:
0 => 2
1 => 4
2 => 6
3 => 6
array(4) {
  [0]=>
  int(2)
  [1]=>
  int(4)
  [2]=>
  int(6)
  [3]=>
  &int(6)
}

Ejemplo #2 Iterar los valores de un array constante por referencia

<?php
foreach ([1, 2, 3, 4] as &$value) {
    $value = $value * 2;
    echo $value . "\n";
}

El ejemplo anterior mostrará:

2
4
6
8

Véase también