extract()

O que é extract() em PHP?

extract() é uma função PHP integrada que importa os elementos de um array associativo para a tabela de símbolos atual — transformando cada chave em uma variável cujo valor é o elemento correspondente do array. É o inverso de compact(), que constrói um array a partir de variáveis existentes.

Sua assinatura é:

extract(array &$array, int $flags = EXTR_OVERWRITE, string $prefix = ""): int

• $array — o array de origem. Apenas chaves string que são nomes de variáveis PHP válidos tornam-se variáveis. Chaves numéricas são ignoradas, a menos que você use uma flag de prefixo.
• $flags — controla como colisões de nome com variáveis existentes são tratadas (veja Flags e comportamento).
• $prefix — uma string adicionada como prefixo aos nomes das variáveis quando uma flag de prefixo é usada.

Retorna o número de variáveis importadas com sucesso.

Como usar extract() em PHP

Comece com um array associativo cujas chaves são os nomes de variáveis que você deseja:

$person = [
    'name'  => 'John Doe',
    'age'   => 30,
    'email' => '[email protected]',
];

extract($person);

echo $name;   // John Doe
echo $age;    // 30
echo $email;  // [email protected]

Após extract($person), três variáveis — $name, $age e $email — existem no escopo atual, cada uma contendo o valor da chave correspondente.

Extraindo apenas algumas chaves

Por padrão, extract() cria variáveis para cada chave. Para importar um subconjunto, filtre o array primeiro com array_intersect_key() e array_flip():

$wanted = ['name', 'email'];
$count = extract(array_intersect_key($person, array_flip($wanted)));

echo $count;  // 2
echo $name;   // John Doe
echo $email;  // [email protected]
// $age is NOT created

array_flip($wanted) transforma ['name', 'email'] em ['name' => 0, 'email' => 1], e array_intersect_key() mantém apenas essas chaves de $person, portanto apenas $name e $email são extraídos.

Flags e comportamento

O segundo parâmetro controla como as variáveis existentes são tratadas quando uma chave colide com uma variável já existente. As flags mais comuns são:

Compare EXTR_OVERWRITE (o padrão) com EXTR_SKIP:

$name = 'Existing Name';
$data = ['name' => 'New Name'];

extract($data);             // default: overwrites
echo $name;                 // New Name

$name = 'Existing Name';
extract($data, EXTR_SKIP);  // keep what's already set
echo $name;                 // Existing Name

Use EXTR_PREFIX_ALL para dar um namespace a cada variável e evitar colisões:

$data = ['name' => 'John', 'age' => 30];
extract($data, EXTR_PREFIX_ALL, 'user');

echo $user_name;  // John
echo $user_age;   // 30

Aviso de segurança

Como extract() cria variáveis dinamicamente a partir das chaves, alimentá-la com dados não confiáveis pode sobrescrever variáveis existentes — incluindo variáveis críticas ou superglobais como $_GET, $_POST e $_SESSION. Uma vulnerabilidade clássica é extract($_GET), que permite a um atacante definir qualquer variável no seu script por meio da query string:

$is_admin = false;
extract($_GET);          // ?is_admin=1 now makes $is_admin truthy — dangerous!

Nunca chame extract() diretamente em dados de requisição. Quando necessário, passe EXTR_SKIP para que as variáveis existentes não sejam substituídas, ou use uma lista de permissões com array_intersect_key() conforme mostrado acima.

Quando usar extract()

extract() é mais útil em situações restritas e controladas:

• Renderização de templates — uma engine de views extrai um array de dados conhecido em variáveis locais antes de incluir um template, para que o template possa usar $title em vez de $data['title'].
• Desempacotamento de configurações — transformar um array de configuração pequeno e confiável em variáveis nomeadas no início de um script.

Na maior parte do código, atribuição explícita é mais clara e segura do que extract(), pois um leitor consegue ver exatamente quais variáveis entram em escopo. Use-a somente quando as chaves forem confiáveis e o ganho de legibilidade for real.

Resumo

extract() importa as chaves de um array associativo como variáveis no escopo atual e retorna quantas foram criadas. Seu comportamento padrão EXTR_OVERWRITE a torna poderosa, mas arriscada: sempre filtre ou use EXTR_SKIP com entradas não confiáveis. Para fazer o caminho inverso — construir um array a partir de variáveis — use compact().

Prática