Estruturas de Controle
PHP Manual

foreach

(PHP 4, PHP 5, PHP 7)

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 (array_expression as $value)
    statement
foreach (array_expression as $key => $value)
    statement

A primeira forma, itera sobre arrays informados na array_expression. A cada iteração, o valor do elemento atual é atribuído a $value e o ponteiro interno do array avança uma posição (então, na próxima iteração, se estará olhando para o próximo elemento).

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

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

Nota:

No PHP 5, quando o foreach inicia sua primeira execução, o ponteiro interno do array é automaticamente redefinido para o primeiro elemento. Isso indica que não é necessário chamar a função reset() antes de um laço foreach.

Como o foreach depende do ponteiro interno do array no PHP 5, modificá-lo dentro de um laço pode levar a comportamentos inesperados.

No PHP 7, o foreach não utiliza o ponteiro interno do array.

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

<?php
$arr 
= array(1234);
foreach (
$arr as &$value) {
    
$value $value 2;
}
// $arr is now array(2, 4, 6, 8)
unset($value); // break the reference with the last element
?>

Aviso

A referência ao $value 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(1234);
foreach (
$arr as &$value) {
    
$value $value 2;
}
// $arr is now array(2, 4, 6, 8)

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

foreach ($arr as $key => $value) {
    
// $arr[3] será atualizado com cada valor de $arr...
    
echo "{$key} => {$value} ";
    
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 )
?>

Em versões anteriores ao PHP 5.5.0, a referência a $value só é possível se o array iterado puder ser referenciado (isso é, se ele for uma variável). O código a seguir só funcionará em versões do PHP superiores a 5.5.0:

<?php
foreach (array(1234) as &$value) {
    
$value $value 2;
}
?>

Nota:

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

Deve-se ter notado que as seguintes funcionalmente idênticas:

<?php
$arr 
= array("one""two""three");
reset($arr);
while (list(, 
$value) = each($arr)) {
    echo 
"Value: $value<br />\n";
}

foreach (
$arr as $value) {
    echo 
"Value: $value<br />\n";
}
?>

Os exemplos a seguir também são funcionalmente idênticos.

<?php
$arr 
= array("one""two""three");
reset($arr);
while (list(
$key$value) = each($arr)) {
    echo 
"Key: $key; Value: $value<br />\n";
}

foreach (
$arr as $key => $value) {
    echo 
"Key: $key; Value: $value<br />\n";
}
?>

Mais alguns exemplos para demonstrar o uso:

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

$a = array(12317);

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(12317);

$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(12345) as $v) {
    echo 
"$v\n";
}
?>

Desempacotando arrays aninhados com o construtor list()

(PHP 5 >= 5.5.0, PHP 7)

O PHP 5.5 adicionou a habilidade de iterar sobre array de arrays e desempacotar arrays aninhados em variáveis do laço fornecendo o construtor list() como valor.

Por exemplo:

<?php
$array 
= [
    [
12],
    [
34],
];

foreach (
$array as list($a$b)) {
    
// $a contains the first element of the nested array,
    // and $b contains the second element.
    
echo "A: $a; B: $b\n";
}
?>

O exemplo acima irá imprimir:

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 
= [
    [
12],
    [
34],
];

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

O exemplo acima irá imprimir:

1
3

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

<?php
$array 
= [
    [
12],
    [
34],
];

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

O exemplo acima irá imprimir:


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:

Changelog

Versão Descrição
7.0.0 foreach não utiliza mais o o ponteiro interno do array.
5.5.0 Referências a $value são suportadas em expressões. Em versões anteriores, apenas variáveis eram suportadas.
5.5.0 Desempacotar arrays aninhados com a função list() é suportado.


Estruturas de Controle
PHP Manual