debug_zval_dump()

Introduction

The debug_zval_dump() function is a built-in PHP function that prints the internal representation of a variable as the Zend engine stores it — not just its value, but also its reference count (refcount) and whether it is a reference (is_ref). This makes it a window into PHP's memory management, especially its copy-on-write optimization.

A zval ("Zend value") is the C-level container PHP uses for every variable. Several variable names can point at the same underlying zval; PHP only makes a physical copy when one of them is modified. debug_zval_dump() lets you watch that bookkeeping happen.

Deprecated and removed. This function was deprecated in PHP 7.2 and removed in PHP 8.0. It runs only on legacy PHP versions (up to 7.4). On PHP 8+ it does not exist — see Modern alternatives below before reaching for it.

If you just want to inspect a variable's type and value, use var_dump() instead — it works on every PHP version and is the everyday debugging tool.

Syntax

The syntax of the debug_zval_dump() function is as follows:

The PHP syntax of the debug_zval_dump()

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

The function accepts one or more variables and prints the internal representation of each. It returns nothing (void) — it writes directly to the output stream. Each line of output follows the pattern:

type(value) refcount(N)

• type(value) — the same type/value notation var_dump() uses, e.g. string(5) "hello", int(42).
• refcount(N) — how many zval handles currently point at this value. When is_ref is set, the output also prints is_ref=true.

Example Usage

Here is an example of how to use the debug_zval_dump() function in PHP:

Example of PHP debug_zval_dump()

Here $b is bound by reference to $a, so both names share one zval marked as a reference. Calling debug_zval_dump() on either prints the same internal value:

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

Why refcount is 3, not 2. You might expect 2 (for $a and $b). The extra count comes from debug_zval_dump() itself: passing the variable into the function temporarily adds one more handle to the zval, which is counted before the value is printed. This off-by-one is a known quirk — read the printed count relative to a baseline rather than as an absolute truth.

Watching copy-on-write

The more instructive use is observing how PHP shares and then splits a value. Plain (non-reference) variables share a zval until one is written to:

<?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
?>

The refcount climbing when you assign and dropping again when you modify a copy is copy-on-write in action — PHP avoided duplicating the "hello" string until it actually had to.

Conclusion

The debug_zval_dump() function was historically useful for inspecting reference counts and Zend engine copy-on-write behavior. It prints a variable's type, value, and refcount/is_ref status, which helped developers reason about when PHP actually copies data. Today it is mostly of educational interest, since it is gone from PHP 8+.

Modern alternatives

Since debug_zval_dump() is unavailable on PHP 8+, reach for these instead:

• var_dump() — the standard choice for inspecting any variable's type and value. Use this for everyday debugging.
• print_r() — human-readable output for arrays and objects, optionally returned as a string.
• var_export() — outputs a valid PHP code representation you can paste back into source.
• gettype() — when you only need a variable's type name.
• xdebug_debug_zval() — the closest replacement for refcount inspection, available when the Xdebug extension is installed.

Practice