PHP 8.1.20 Released!

foreach

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

O construtor foreach fornece uma maneira fácil de iterar sobre arrays. O foreach funciona somente em arrays e objetos, e emitirá um erro ao tentar usá-lo em uma variável com um tipo de dado diferente ou em uma variável não inicializada. Possui duas sintaxes:

foreach (iterable_expression as $valor)
    statement
foreach (iterable_expression as $chave => $valor)
    statement

A primeira forma percorre o iterável dado por iterable_expression. A cada iteração, o valor do elemento atual é atribuído a $valor.

A segunda forma var, adicionalmente, atribuir a chave do elemento corrente a variável $chave a cada iteração.

Note que o foreach não modifica o ponteiro interno do array, que é usado por funções como current() e key().

É possível customizar a iteração em objetos.

Para modificar diretamente elementos de um array dentro de um laço, preceda $valor com &. Neste caso, o valor será atribuído por referência.

<?php
$arr
= array(1, 2, 3, 4);
foreach (
$arr as &$valor) {
$valor = $valor * 2;
}
// $arr is now array(2, 4, 6, 8)
unset($valor); // quebra a referência com o último elemento
?>

Aviso

A referência ao $valor e o último elemento do array permanecerá inalterado mesmo após a iteração do foreach. É recomendado destruí-lo utilizando a função unset(). Caso contrário você experienciará o seguinte comportamento:

<?php
$arr
= array(1, 2, 3, 4);
foreach (
$arr as &$valor) {
$valor = $valor * 2;
}
// $arr agora é array(2, 4, 6, 8)

// sem um unset($valor), $valor continuará como referência ao último item: $arr[3]

foreach ($arr as $chave => $valor) {
// $arr[3] será atualizado com cada valor de $arr...
echo "{$chave} => {$valor} ";
print_r($arr);
}
// ...até que, o segundo e último valor é copiado para o último valor

// saída:
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
?>

É possível iterar o valor de um array constante por referência

<?php
foreach (array(1, 2, 3, 4) as &$valor) {
$valor = $valor * 2;
}
?>

Nota:

O foreach não possui suporte a habilidade de suprimir mensagens de erro utilizando @.

Mais alguns exemplos para demonstrar o uso:

<?php
/* foreach example 1: value only */

$a = array(1, 2, 3, 17);

foreach (
$a as $v) {
echo
"Current value of \$a: $v.\n";
}

/* foreach example 2: value (with its manual access notation printed for illustration) */

$a = array(1, 2, 3, 17);

$i = 0; /* for illustrative purposes only */

foreach ($a as $v) {
echo
"\$a[$i] => $v.\n";
$i++;
}

/* foreach example 3: key and value */

$a = array(
"one" => 1,
"two" => 2,
"three" => 3,
"seventeen" => 17
);

foreach (
$a as $k => $v) {
echo
"\$a[$k] => $v.\n";
}

/* foreach example 4: multi-dimensional arrays */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach (
$a as $v1) {
foreach (
$v1 as $v2) {
echo
"$v2\n";
}
}

/* foreach example 5: dynamic arrays */

foreach (array(1, 2, 3, 4, 5) as $v) {
echo
"$v\n";
}
?>

Desempacotando arrays aninhados com o construtor list()

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

É possível iterar sobre um array de arrays e desempacotar arrays aninhados em variáveis do laço fornecendo o construtor list() como valor.

Por exemplo:

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

foreach (
$array as list($a, $b)) {
// $a contém o primeiro elemento do array aninhado,
// e $b contém o segundo elemento.
echo "A: $a; B: $b\n";
}
?>

O exemplo acima produzirá:

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

Pode-se se fornecer menos elementos ao construtor list() aos que existem no array aninhado, neste caso, os valores do array que sobrarem serão ignorados.

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

foreach (
$array as list($a)) {
// Note that there is no $b here.
echo "$a\n";
}
?>

O exemplo acima produzirá:

1
3

Um aviso será gerado se não houver elementos suficientes no array para o preenchimento do construtor list():

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

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

O exemplo acima produzirá:


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:

add a note

User Contributed Notes 3 notes

up
12
Okafor Chiagozie
8 months ago
An easier way to unpack nested array elements

$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as [$a, $b]) {
    echo "A: $a; B: $b\n";
}
up
4
Sanusi Hassan
8 months ago
destructure array elements

you can unpac nested array elements using the following

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

foreach (
$array as $v) {
    [
$a, $b] = $v;
    echo
"A: $a; B: $b\n";
}
?>
up
-47
jon at pearkins dot com
8 months ago
For an array, foreach presents the elements of the array in the order that they were added to the array. For example, if you need to have the elements presented in ascending order by key, use the ksort function to rearrange the elements of the array in key sequence.

This behavior is a result of the way that PHP arrays are stored. foreach merely presents the elements of an array in the order that they are stored within the array.
To Top