Quite often, functions in PHP either accept or return an array or object implementing the \Traversable interface. Though both types can be used in the foreach constructs, fundamentally, an array is a primitive type; objects are not. This made it difficult for functions to reason about these types of iterative parameters and return values.

PHP 7.1 addresses this need by introducing the iterable pseudo-type to the mix. The idea is to use it as a type declaration on a parameter or return type to indicate that the value is iterable. The iterable type accepts any array, any object implementing Traversable, and generators.

The following example demonstrates the use of iterable as a function parameter:

function import(iterable $users) 
 {
   // ...
 }

function import(iterable $users = null) 
 {
   // ...
 }

function import(iterable $users = []) 
 {
   // ...
 }

Trying to pass the value to the preceding import function other than an array instance of Traversable or generator will throw \TypeError. If, however, the default value is assigned, be it null or an empty array, the function will work.

The following examples demonstrates the use of iterable as a function return value:

 function export(): iterable {
   return [
     'Johny',
     'Tom',
     'Matt'
   ];
 }

 function mix(): iterable {
   return [
     'Welcome',
      33,
      4200.00
   ];
 }

 function numbers(): iterable {
    for ($i = 0; $i <= 5; $i++) {
       yield $i;
    }
 }

One thing to be careful about is that iterable is implemented as a reserved class name in PHP. What this means is that any user class, interface, or trait named iterable will throw an error.