is_iterable()

Introduction

is_iterable() est une fonction PHP native (disponible depuis PHP 7.1) qui indique si une valeur peut être parcourue avec une boucle foreach. Elle retourne true pour exactement deux types de valeurs :

• Les tableaux — tout tableau est itérable.
• Les objets qui implémentent l'interface Traversable — en pratique, cela désigne les objets implémentant Iterator ou IteratorAggregate, ainsi que les générateurs (fonctions utilisant yield).

Tout le reste — chaînes, entiers, booléens, null et objets simples (comme stdClass) — n'est pas itérable, même s'il ressemble intuitivement à une liste. Cette page couvre la syntaxe, ce qui est considéré comme itérable, les pièges les plus courants et les cas où utiliser is_iterable() s'avère vraiment utile.

Syntaxe

is_iterable(mixed $value): bool

Elle prend un seul argument, $value, et retourne un boolean :

Depuis PHP 8.0, il existe également un pseudo-type correspondant, iterable, utilisable comme déclaration de type — voir Quand l'utiliser ci-dessous.

Exemple de base

$var1 est un tableau, il est donc itérable. $var2 est une chaîne — bien qu'on puisse accéder à ses caractères un par un, il est impossible de la parcourir avec foreach, donc is_iterable() retourne false.

Ce qui est considéré comme itérable

Les cas intéressants concernent les objets. Un objet n'est itérable que s'il implémente Traversable (directement ou via Iterator/IteratorAggregate), ou s'il s'agit d'un générateur. Un objet simple ne l'est pas.

<?php
function genFn() {
    yield 1;
    yield 2;
}

class MyCollection implements IteratorAggregate {
    private array $items = [1, 2, 3];

    public function getIterator(): Iterator {
        return new ArrayIterator($this->items);
    }
}

var_dump(is_iterable([1, 2, 3]));      // bool(true)  array
var_dump(is_iterable(genFn()));        // bool(true)  generator
var_dump(is_iterable(new MyCollection())); // bool(true)  Traversable
var_dump(is_iterable("hello"));        // bool(false) string
var_dump(is_iterable(42));             // bool(false) int
var_dump(is_iterable(new stdClass())); // bool(false) plain object
var_dump(is_iterable(null));           // bool(false) null
?>

Le point essentiel à retenir : un stdClass (ou tout objet sans Traversable) retourne false, même si foreach peut parcourir ses propriétés publiques. is_iterable() ne signale délibérément que les valeurs qui sont itérables par contrat, pas par accident.

Pièges courants

• Les chaînes ne sont pas itérables. Une chaîne est un scalaire, pas une collection, donc is_iterable("abc") est false. Pour vérifier si une valeur est une chaîne, utilisez is_string() à la place.
• Les objets simples échouent. is_iterable(new stdClass()) est false. Si vous souhaitez seulement savoir si une valeur est un quelconque objet, utilisez is_object() ; si vous avez besoin spécifiquement d'un objet pouvant être parcouru, is_iterable() est le bon choix.
• Ce n'est pas la même chose que is_array(). is_array() est true uniquement pour les tableaux et rejette les générateurs et les objets Traversable. Utilisez is_iterable() quand vous souhaitez accepter à la fois les tableaux et les objets itérateurs.
• null retourne false. Passer une valeur non initialisée ou null est sans danger — la fonction retourne simplement false sans lever d'erreur.

Quand l'utiliser

Utilisez is_iterable() comme clause de garde avant un foreach, afin qu'une fonction puisse accepter indifféremment un tableau ou un itérateur paresseux sans planter sur une entrée invalide :

<?php
function sumAll(mixed $data): int {
    if (!is_iterable($data)) {
        throw new InvalidArgumentException('Expected an iterable.');
    }

    $total = 0;
    foreach ($data as $value) {
        $total += $value;
    }
    return $total;
}

echo sumAll([1, 2, 3, 4]), "\n"; // 10

function counter() {
    yield 5;
    yield 10;
}
echo sumAll(counter()), "\n";     // 15
?>

La même fonction gère un tableau simple et un générateur, car les deux satisfont is_iterable().

Le choix le plus élégant est souvent la déclaration de type iterable (PHP 7.1+), qui laisse PHP vérifier la contrainte à votre place, vous évitant ainsi la vérification manuelle :

<?php
function sumAll(iterable $data): int {
    $total = 0;
    foreach ($data as $value) {
        $total += $value;
    }
    return $total;
}
?>

Utilisez la fonction is_iterable() lorsque la valeur est mixed et que vous souhaitez brancher à l'exécution ; utilisez le type hint iterable lorsque l'itérabilité est une exigence absolue du paramètre.

Conclusion

is_iterable() répond à une question précise : cette valeur peut-elle être parcourue par une boucle foreach ? Elle retourne true pour les tableaux et les objets Traversable (y compris les générateurs), et false pour tout le reste. Utilisez-la comme garde à l'exécution pour des entrées mixed, préférez le type hint iterable quand l'itérabilité est obligatoire, et n'oubliez pas qu'elle est plus stricte qu'il n'y paraît — les chaînes et les objets simples ne sont pas itérables. Pour les vérifications associées, consultez is_array(), is_object() et gettype().

Pratique