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 (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çoforeach
.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(1, 2, 3, 4);
foreach ($arr as &$value) {
$value = $value * 2;
}
// $arr is now array(2, 4, 6, 8)
unset($value); // break the reference with the last element
?>
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(1, 2, 3, 4);
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(1, 2, 3, 4) as &$value) {
$value = $value * 2;
}
?>
Nota:
O
foreach
não possui suporte a habilidade de suprimir mensagens de erro utilizando o '@'.
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";
}
?>
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
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 = [
[1, 2],
[3, 4],
];
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 = [
[1, 2],
[3, 4],
];
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 = [
[1, 2],
[3, 4],
];
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:
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. |