get_defined_vars()

Introdução

get_defined_vars() é uma função PHP embutida que retorna um array associativo com todas as variáveis existentes no escopo onde ela é chamada. As chaves do array são os nomes das variáveis (sem o $ inicial) e os valores são os valores atuais dessas variáveis.

A ideia central a lembrar é o escopo. Um "escopo" é a região do código em que uma variável é visível. PHP tem escopo de função (variáveis dentro de uma função) e escopo global (variáveis no nível superior de um script). get_defined_vars() relata apenas o que é visível no ponto exato onde você a chama, o que a torna uma forma rápida de capturar o estado para depuração sem precisar nomear cada variável manualmente.

Esta página aborda a sintaxe, o que a função faz e o que ela não inclui, como seu resultado muda com o escopo e os casos de uso mais comuns no mundo real.

Sintaxe

get_defined_vars(): array

A função não aceita nenhum argumento e sempre retorna um array. Se nenhuma variável estiver definida no escopo atual, ela retorna um array vazio.

Exemplo básico

O caso mais simples é chamá-la no escopo global, logo após definir algumas variáveis:

<?php
$name = "Ada";
$age = 36;
$colors = ["red", "green"];

print_r(get_defined_vars());
?>

As variáveis definidas pelo usuário aparecem como chaves (junto com as superglobais do PHP, explicadas abaixo):

Array
(
    [name] => Ada
    [age] => 36
    [colors] => Array
        (
            [0] => red
            [1] => green
        )
    ...
)

O escopo importa: local vs. global

Esta é a parte que confunde as pessoas. get_defined_vars() não enxerga além dos limites do escopo. Uma função não pode ver as variáveis globais do script, a menos que tenham sido importadas (por exemplo, com a palavra-chave global ou passadas como argumentos); portanto, chamar get_defined_vars() dentro de uma função relata apenas as variáveis locais daquela função.

Dentro da função, apenas a variável local é visível, portanto a saída é apenas:

Array
(
    [var3] => 1
)

As variáveis globais $var1 e $var2 não são listadas, pois pertencem a um escopo diferente. (true é exibido como 1 porque o PHP renderiza o boolean true dessa forma no print_r.)

E quanto às superglobais?

Um equívoco comum é achar que get_defined_vars() sempre retorna as superglobais ($_GET, $_POST, $_SERVER etc.). Isso não é verdade. As superglobais são retornadas somente quando você chama a função no escopo global, porque é onde elas existem. Dentro de uma função, elas são acessíveis pelo nome, mas não fazem parte daquele escopo local, por isso não aparecem no resultado acima. A mesma regra se aplica a $GLOBALS — ele não é incluído no array retornado.

Casos de uso comuns

Verificar se uma variável está definida

Como o resultado é um array simples, você pode verificar a existência de uma variável com array_key_exists(). Isso é útil quando uma variável pode estar definida apenas em alguns caminhos do código:

<?php
$config = "loaded";

$vars = get_defined_vars();

var_dump(array_key_exists("config", $vars));   // bool(true)
var_dump(array_key_exists("missing", $vars));  // bool(false)
?>

Para verificar uma única variável conhecida, isset() costuma ser mais claro; get_defined_vars() se destaca quando você quer obter o quadro completo de uma vez.

Depurar o estado dentro de uma função

Insira uma única chamada próxima a uma linha problemática para ver cada variável local e seu valor, em vez de escrever um var_dump() para cada uma:

<?php
function calculatePrice($base, $taxRate) {
  $tax = $base * $taxRate;
  $total = $base + $tax;

  print_r(get_defined_vars());
  return $total;
}

calculatePrice(100, 0.2);
?>

O instantâneo mostra os argumentos e cada variável local ao longo do caminho:

Array
(
    [base] => 100
    [taxRate] => 0.2
    [tax] => 20
    [total] => 120
)

Funções relacionadas

Veja também Escopo de variáveis para as regras que governam o que get_defined_vars() pode ver, e Superglobais do PHP para entender por que elas aparecem apenas no escopo global.

Conclusão

get_defined_vars() fornece um instantâneo em uma única linha de todas as variáveis visíveis no escopo atual, o que a torna um auxílio rápido para depuração e uma forma simples de inspecionar ou testar o estado de forma programática. A única regra a ter em mente é o escopo: dentro de uma função você vê apenas as variáveis locais daquela função (mais qualquer coisa importada explicitamente), enquanto no escopo global você também vê as superglobais do PHP. Conhecer esse limite é o que torna a função previsível de usar.

Prática