foreach
(PHP 4, PHP 5, PHP 7, PHP 8)
O construtor foreach fornece uma maneira fácil de
iterar sobre arrays e objetos Traversable.
O foreach emitirá um erro quando usado com
uma variável contendo um tipo de dado diferente ou com uma variável não inicializada.
A primeira forma percorre o iterável dado por
iterable_expression. A cada iteração, o valor
do elemento atual é atribuído à variável $valor.
A segunda forma irá, adicionalmente, atribuir a chave do elemento corrente à
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.
Exemplo #1 Usos comuns de foreach
<?php
/* Exemplo: somente valor */
$array = [1, 2, 3, 17];
foreach ($array as $value) {
echo "Elemento atual de \$array: $value.\n";
}
/* Exemplo: chave e valor */
$array = [
"um" => 1,
"dois" => 2,
"três" => 3,
"dezessete" => 17
];
foreach ($array as $key => $value) {
echo "Chave: $key => Valor: $value\n";
}
/* Exemplo: arrays chave-valor multidimensionais */
$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 na posição x=$x e y=$y: $value\n";
}
}
/* Exemplo: arrays dinâmicos */
foreach (range(1, 5) as $value) {
echo "$value\n";
}
?>
Nota:
foreach não suporta a capacidade de
supressão de mensagens de erro usando o operador
@.
Desempacotando arrays aninhados
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
É possível iterar sobre um array de arrays e desempacotar o array aninhado
em variáveis do laço usando
desconstrução de array
através de [] ou usando a construção de linguagem list()
como o valor.
Nota:
Observe que a
desconstrução de array
através de [] só é possível a partir do PHP 7.1.0.
Ao fornecer menos variáveis que o número de elementos no array,
os elementos restantes serão ignorados.
Da mesma forma, elementos podem ser pulados usando uma vírgula:
Um aviso será gerado se não houver elementos suficientes no array para o preenchimento
do construtor list():
foreach e referências
É possível modificar elementos de array diretamente dentro de um laço, precedendo
$value com &.
Neste caso, o valor será atribuído por
referência.
Aviso
A referência a um $value do último elemento do array
permanece mesmo depois do laço foreach. É recomendado
destruir essas referências usando unset().
Caso contrário, o comportamento a seguir irá ocorrer:
Exemplo #2 Iterando valores de um array constante por referência
<?php
foreach ([1, 2, 3, 4] as &$value) {
$value = $value * 2;
}
?>