Não é um tipo, é um pseudo tipo (tal como o callable
). A função dele é indicar que a função aceita como parâmetro tanto array
como qualquer objeto que implementa a interface Traversable
. Ou seja, aceita também objetos do tipo array-like, que funcionam em um loop foreach
.
Se indicado no parâmetro de uma função, a mesma aceitará valores do tipo array
, Iterator
, Generator
, etc. Se não for nenhum destes tipos, uma exceção do tipo TypeError
é disparada.
function foo(iterable $iterable) {
foreach ($iterable as $value) {
// ...
}
}
Pode também ser utilizado para definir o retorno de uma função:
function bar(): iterable {
return [1, 2, 3];
}
Quando utilizado em parâmetros, o mesmo pode possuir valor padrão null
ou mesmo um array
vazio.
function foo(iterable $iterable = null) {
// ...
}
E como o generator
é um sub-tipo de Traversable
, o seguinte é válido:
function gen(): iterable {
yield 1;
yield 2;
yield 3;
}
Basicamente, para saber se é um tipo possível de iterable
, basta utilizar a função is_iterable
:
var_dump(is_iterable([1, 2, 3])); // bool(true)
var_dump(is_iterable(new ArrayIterator([1, 2, 3]))); // bool(true)
var_dump(is_iterable((function () { yield 1; })())); // bool(true)
var_dump(is_iterable(1)); // bool(false)
var_dump(is_iterable(new stdClass())); // bool(false)
A palavra iterable
é definida como uma palavra reservada para nomes de classes, portanto classes, interfaces e traits não podem ser nomeadas como iterable
.
Nota: por mais que o PHP permita utilizar o foreach
sobre objetos, iterando sobre as propriedades públicas do mesmo, o objeto não será considerado iterable
se não for do tipo Traversable
.
Referência: PHP RFC: Iterable