instanceof

L'opérateur PHP instanceof

instanceof est un opérateur PHP de vérification de type. Il retourne un booléen (true ou false) qui indique si un objet appartient à une classe donnée — ou, plus utilement, s'il appartient à une classe parente dans la chaîne d'héritage ou s'il implémente une interface donnée.

Cette page couvre la syntaxe, le comportement de instanceof vis-à-vis de l'héritage et des interfaces, son utilisation avec un nom de classe stocké dans une variable, les cas limites qui surprennent (non-objets, null, noms de classe inconnus), et quand y recourir plutôt qu'à une alternative plus propre.

Si les classes et les objets vous sont inconnus, lisez d'abord Classes et objets PHP.

Syntaxe

$object instanceof ClassName

L'expression s'évalue à true lorsque $object est une instance de ClassName, de toute classe qui étend ClassName, ou de toute classe qui implémente ClassName (lorsque ClassName est une interface). Sinon, elle s'évalue à false. Notez qu'il n'y a pas de syntaxe d'appel de méthode — instanceof est un opérateur, comme ===, et non une fonction.

Une vérification de base

<?php

class MyClass {}
class MyOtherClass {}

$object = new MyClass();

if ($object instanceof MyClass) {
    echo "The object is an instance of MyClass.";
} else {
    echo "The object is not an instance of MyClass.";
}
// Output: The object is an instance of MyClass.

var_dump($object instanceof MyOtherClass);
// Output: bool(false)

$object a été créé à partir de MyClass, donc la première vérification est true. Il n'a aucun lien avec MyOtherClass, donc cette vérification est false. Les deux classes ne sont pas liées, même si elles se ressemblent.

instanceof et l'héritage

La vraie valeur de instanceof est qu'il remonte la chaîne d'héritage. Un objet enfant est une instance de sa classe parente, donc la vérification réussit pour chaque ancêtre.

<?php

class Fruit {}
class Apple extends Fruit {}
class Banana extends Fruit {}

$apple = new Apple();

var_dump($apple instanceof Apple);   // bool(true)  — its own class
var_dump($apple instanceof Fruit);   // bool(true)  — its parent class
var_dump($apple instanceof Banana);  // bool(false) — a sibling class

$apple passe la vérification Fruit parce que Apple étend Fruit. Il échoue la vérification Banana parce que Apple et Banana sont des classes sœurs — aucune n'hérite de l'autre. Apprenez-en plus dans Héritage PHP.

instanceof et les interfaces

instanceof est le plus souvent utilisé avec les interfaces. Comme toute classe qui implémente une interface compte comme une instance de celle-ci, vous pouvez tester une capacité sans vous soucier de la classe concrète.

<?php

interface Drawable {
    public function draw(): string;
}

class Circle implements Drawable {
    public function draw(): string { return "○"; }
}

class Square implements Drawable {
    public function draw(): string { return "□"; }
}

$shapes = [new Circle(), new Square(), "not a shape"];

foreach ($shapes as $shape) {
    if ($shape instanceof Drawable) {
        echo $shape->draw();
    }
}
// Output: ○□

La chaîne "not a shape" est ignorée car ce n'est pas un Drawable. C'est l'usage quotidien : filtrer une liste mixte pour ne garder que les objets qui supportent le comportement recherché. Consultez Interfaces PHP pour une vue complète.

Utiliser un nom de classe depuis une variable

Le côté droit peut être une variable de type string contenant un nom de classe ou d'interface. C'est pratique lorsque le type est déterminé à l'exécution.

<?php

class Fruit {}
class Apple extends Fruit {}

$apple = new Apple();
$type  = 'Fruit';

var_dump($apple instanceof $type);   // bool(true)

Vous pouvez également comparer deux objets — $a instanceof $b fonctionne lorsque $b est un objet, en vérifiant si $a est une instance de la classe de $b.

Cas limites et pièges

instanceof ne lève jamais d'exception et n'émet jamais d'avertissement. Lorsque l'opérande gauche n'est pas un objet, il retourne simplement false.

<?php

class Fruit {}

var_dump(null instanceof Fruit);      // bool(false)
var_dump("Fruit" instanceof Fruit);   // bool(false) — a string is not an object
var_dump(42 instanceof Fruit);        // bool(false)

Cela rend instanceof sûr à utiliser comme garde avant d'appeler une méthode, sans avoir besoin de vérifier d'abord is_object(). Si vous avez seulement besoin de savoir si une valeur est un objet (de n'importe quelle classe), utilisez plutôt is_object().

Un point subtil : si vous passez un nom de classe qui n'existe pas comme littéral de chaîne du côté droit, PHP n'effectue pas d'autoload et ne génère pas d'erreur — il retourne simplement false. Ainsi, une faute de frappe dans le nom de classe échoue silencieusement. Préférez le nom de classe nu ($x instanceof Fruit) à une chaîne lorsque c'est possible, afin que le parseur le valide.

Quand utiliser instanceof — et quand ne pas l'utiliser

Utilisez instanceof lorsque vous avez réellement une valeur dont vous ne pouvez pas garantir le type : des données issues de json_decode, une collection mixte, un plugin retourné par du code utilisateur, ou un bloc catch affinant une exception.

<?php

try {
    throw new InvalidArgumentException("bad input");
} catch (Exception $e) {
    if ($e instanceof InvalidArgumentException) {
        echo "Caught an argument error: " . $e->getMessage();
    }
}
// Output: Caught an argument error: bad input

Évitez de parsemer votre code de vérifications instanceof pour brancher sur le type — les longues chaînes if ($x instanceof A) … elseif ($x instanceof B) signifient généralement qu'une méthode devrait être définie sur chaque classe et appelée de façon polymorphique à la place. Recourez à instanceof pour garder une opération, non pour remplacer l'héritage.

Résumé

• $object instanceof ClassName retourne true si l'objet est une instance de la classe, d'une sous-classe, ou d'une interface implémentée.
• Il remonte la chaîne d'héritage complète et correspond aux interfaces — c'est ce qui le rend puissant.
• Il retourne false (jamais une erreur) pour null, les scalaires et autres non-objets, il est donc sûr comme garde.
• Un nom de classe inexistant passé comme chaîne retourne false silencieusement ; préférez le nom de classe nu.
• Utilisez-le pour vérifier le type d'une valeur inconnue avant d'agir dessus, pas comme substitut au polymorphisme.

Pratique