debug_zval_dump()

Introdução

A função debug_zval_dump() é uma função integrada do PHP que imprime a representação interna de uma variável tal como a engine Zend a armazena — não apenas seu valor, mas também sua contagem de referências (refcount) e se é uma referência (is_ref). Isso a torna uma janela para o gerenciamento de memória do PHP, especialmente sua otimização de cópia por escrita (copy-on-write).

Um zval ("Zend value") é o contêiner de nível C que o PHP usa para cada variável. Vários nomes de variáveis podem apontar para o mesmo zval subjacente; o PHP só faz uma cópia física quando um deles é modificado. debug_zval_dump() permite observar essa contabilidade em ação.

Obsoleta e removida. Esta função foi descontinuada no PHP 7.2 e removida no PHP 8.0. Ela funciona apenas em versões legadas do PHP (até 7.4). No PHP 8+ ela não existe — veja Alternativas modernas abaixo antes de utilizá-la.

Se você simplesmente quer inspecionar o tipo e o valor de uma variável, use var_dump() — ela funciona em todas as versões do PHP e é a ferramenta de depuração do dia a dia.

Sintaxe

A sintaxe da função debug_zval_dump() é a seguinte:

A sintaxe PHP de debug_zval_dump()

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

A função aceita uma ou mais variáveis e imprime a representação interna de cada uma. Ela não retorna nada (void) — escreve diretamente no fluxo de saída. Cada linha de saída segue o padrão:

type(value) refcount(N)

• type(value) — a mesma notação de tipo/valor que var_dump() usa, por exemplo string(5) "hello", int(42).
• refcount(N) — quantos identificadores zval apontam atualmente para esse valor. Quando is_ref está definido, a saída também exibe is_ref=true.

Exemplo de Uso

Aqui está um exemplo de como usar a função debug_zval_dump() em PHP:

Exemplo de debug_zval_dump() em PHP

Aqui $b é vinculado por referência a $a, então ambos os nomes compartilham um zval marcado como referência. Chamar debug_zval_dump() em qualquer um deles imprime o mesmo valor interno:

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

Por que refcount é 3, e não 2. Você pode esperar 2 (para $a e $b). A contagem extra vem da própria debug_zval_dump(): passar a variável para a função adiciona temporariamente mais um identificador ao zval, que é contado antes de o valor ser impresso. Este desvio de um é uma peculiaridade conhecida — leia a contagem impressa em relação a uma linha de base, e não como uma verdade absoluta.

Observando a cópia por escrita

O uso mais instrutivo é observar como o PHP compartilha e depois separa um valor. Variáveis comuns (sem referência) compartilham um zval até que uma delas seja modificada:

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

O refcount subindo quando você faz a atribuição e caindo novamente quando você modifica uma cópia é a cópia por escrita em ação — o PHP evitou duplicar a string "hello" até que realmente precisasse.

Conclusão

A função debug_zval_dump() foi historicamente útil para inspecionar contagens de referências e o comportamento de cópia por escrita da engine Zend. Ela imprime o tipo, o valor e o status refcount/is_ref de uma variável, o que ajudava os desenvolvedores a entender quando o PHP realmente copiava dados. Hoje ela é de interesse principalmente educacional, uma vez que foi removida do PHP 8+.

Alternativas modernas

Como debug_zval_dump() não está disponível no PHP 8+, utilize estas alternativas:

• var_dump() — a escolha padrão para inspecionar o tipo e o valor de qualquer variável. Use para depuração no dia a dia.
• print_r() — saída legível para arrays e objetos, opcionalmente retornada como string.
• var_export() — gera uma representação em código PHP válido que pode ser colada de volta no código-fonte.
• gettype() — quando você precisa apenas do nome do tipo de uma variável.
• xdebug_debug_zval() — o substituto mais próximo para inspeção de refcount, disponível quando a extensão Xdebug está instalada.

Prática