debug_zval_dump()

Introduction

La fonction debug_zval_dump() est une fonction PHP intégrée qui affiche la représentation interne d'une variable telle que le moteur Zend la stocke — pas seulement sa valeur, mais aussi son compteur de références (refcount) et s'il s'agit d'une référence (is_ref). C'est donc une fenêtre sur la gestion mémoire de PHP, en particulier son optimisation copy-on-write.

Un zval ("Zend value") est le conteneur au niveau C que PHP utilise pour chaque variable. Plusieurs noms de variables peuvent pointer vers le même zval sous-jacent ; PHP n'effectue une copie physique que lorsque l'une d'elles est modifiée. debug_zval_dump() permet d'observer cette comptabilité en action.

Dépréciée et supprimée. Cette fonction a été dépréciée en PHP 7.2 et supprimée en PHP 8.0. Elle ne s'exécute que sur les versions PHP legacy (jusqu'à 7.4). Sur PHP 8+, elle n'existe pas — consultez les alternatives modernes ci-dessous avant de l'utiliser.

Si vous souhaitez simplement inspecter le type et la valeur d'une variable, utilisez var_dump() à la place — elle fonctionne sur toutes les versions de PHP et constitue l'outil de débogage quotidien.

Syntaxe

La syntaxe de la fonction debug_zval_dump() est la suivante :

La syntaxe PHP de debug_zval_dump()

void debug_zval_dump(mixed $variable, mixed ...$rest): void

La fonction accepte une ou plusieurs variables et affiche la représentation interne de chacune. Elle ne retourne rien (void) — elle écrit directement dans le flux de sortie. Chaque ligne de sortie suit le schéma :

type(value) refcount(N)

• type(value) — la même notation type/valeur qu'utilise var_dump(), par exemple string(5) "hello", int(42).
• refcount(N) — le nombre de handles zval pointant actuellement vers cette valeur. Lorsque is_ref est activé, la sortie affiche également is_ref=true.

Exemple d'utilisation

Voici un exemple d'utilisation de la fonction debug_zval_dump() en PHP :

Exemple de debug_zval_dump() en PHP

Ici $b est lié par référence à $a, donc les deux noms partagent un seul zval marqué comme référence. Appeler debug_zval_dump() sur l'un ou l'autre affiche la même valeur interne :

string(5) "hello" refcount(3)
string(5) "hello" refcount(3)

Pourquoi refcount vaut 3 et non 2. On pourrait s'attendre à 2 (pour $a et $b). Le compte supplémentaire provient de debug_zval_dump() elle-même : passer la variable dans la fonction ajoute temporairement un handle de plus au zval, lequel est comptabilisé avant l'affichage. Cet décalage d'un est un comportement connu — lisez le compte affiché par rapport à une valeur de base plutôt que comme une vérité absolue.

Observer le copy-on-write

L'utilisation la plus instructive est d'observer comment PHP partage puis sépare une valeur. Les variables ordinaires (non référencées) partagent un zval jusqu'à ce que l'une d'elles soit modifiée :

<?php
$a = "hello";
debug_zval_dump($a);   // refcount(2): $a + the function argument

$b = $a;               // no copy yet — $a and $b share one zval
debug_zval_dump($a);   // refcount(3): $a, $b, and the argument

$b = "world";          // write triggers the copy ("copy-on-write")
debug_zval_dump($a);   // back to refcount(2): $b now has its own zval
?>

Le refcount qui augmente lors d'une affectation et diminue à nouveau lors de la modification d'une copie illustre le copy-on-write en action — PHP a évité de dupliquer la chaîne "hello" jusqu'à ce que ce soit réellement nécessaire.

Conclusion

La fonction debug_zval_dump() était historiquement utile pour inspecter les compteurs de références et le comportement copy-on-write du moteur Zend. Elle affiche le type, la valeur et le statut refcount/is_ref d'une variable, ce qui aidait les développeurs à comprendre quand PHP copie réellement les données. Aujourd'hui, elle présente surtout un intérêt pédagogique, car elle a été supprimée de PHP 8+.

Alternatives modernes

Puisque debug_zval_dump() n'est pas disponible sur PHP 8+, préférez les options suivantes :

• var_dump() — le choix standard pour inspecter le type et la valeur de n'importe quelle variable. À utiliser pour le débogage quotidien.
• print_r() — sortie lisible par l'humain pour les arrays et les objects, éventuellement retournée sous forme de string.
• var_export() — produit une représentation PHP valide que vous pouvez réinsérer dans le code source.
• gettype() — lorsque vous avez seulement besoin du nom du type d'une variable.
• xdebug_debug_zval() — le remplacement le plus proche pour l'inspection du refcount, disponible lorsque l'extension Xdebug est installée.

Pratique