Manual do PHP
Anterior |  | Próxima

# extract

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

extract -- Importa variáveis para a tabela de símbolos a partir de um array

## Descrição

int extract ( array var_array [, int extract_type [, string prefix]] )

Essa função é usada para importar variáveis a partir de um array para a tabela de símbolos corrente. Recebe o array associativo `var_array` e trata as suas chaves como os nomes das variáveis e os valores como valores das variáveis. Para cada par chave/valor ele criará uma variável na tabela de símbolos corrente, seguindo os parâmetros `extract_type` e `prefix`.

> Nota: Iniciado com a versão 4.0.5, esta função devolve o número de variáveis extraídas.

> Nota: `EXTR_IF_EXISTS` e `EXTR_PREFIX_IF_EXISTS` foi introduzido na versão 4.2.0.

> Nota: `EXTR_REFS` foi introduzido na versão 4.3.0.

extract() checa se cada chave do array constitui um nome de variável válido e por colisões com as variáveis já existentes na tabela de símbolos. O modo com que chaves inválidas ou númericas e colisões são tratadas é determinado pelo argumento `extract_type`. Esse argumento pode receber os seguintes valores:

`EXTR_OVERWRITE`

  Se houver uma colisão, sobrescreve a variável existente.

`EXTR_SKIP`

  Se houver uma colisão, não sobrescreve a variável existente.

`EXTR_PREFIX_SAME`

  Se houver uma colisão, adiciona um prefixo ao nome da variável definido pelo argumento `prefix`.

`EXTR_PREFIX_ALL`

  Adiciona um prefixo ao nome de todas as variáveis definido por `prefix`. Desde o PHP 4.0.5 estão incluídos nomes numéricos.

`EXTR_PREFIX_INVALID`

  Adiciona um prefixo definido por `prefix` apenas para variáveis como nomes inválidos ou numéricos. Essa opção foi adicionada no PHP 4.0.5.

`EXTR_IF_EXISTS`

  Só sobrescreve a variável se ela já existe na tabela de símbolos corrente, caso contrário, não faz nada. Isso é útil quando se quer definir uma lista de variáveis válidas e então extrair só as que foram definidas em $_REQUEST, por exemplo. Essa opção foi adicionada no PHP 4.2.0.

`EXTR_PREFIX_IF_EXISTS`

  Só cria nomes de variáveis usando o prefixo se na tabela de símbolos já existe uma variável com o nome sem esse prefixo. Essa opção foi adicionada no PHP 4.2.0.

`EXTR_REFS`

  Extrai variáveis como referências, ou seja, os valores das variáveis importadas ainda estarão referenciando os valores do parâmetro `var_array`. Essa opção pode ser usada sozinha ou em conjunto com as outras usando o operador 'ou' em `extract_type`. Essa opação foi adicionada no PHP 4.3.0.

Se `extract_type` não for especificado, é assumido o valor `EXTR_OVERWRITE`por padrão.

Note que `prefix` só é necessário se `extract_type` for `EXTR_PREFIX_SAME`, `EXTR_PREFIX_ALL`, ou `EXTR_PREFIX_INVALID` ou `EXTR_PREFIX_IF_EXISTS`. Se o nome com o prefixo não for um nome de variável válido, ela não será importada para a tabela de símbolos.

extract() retorna o número de variáveis importadas com sucesso para a tabela de símbolos.

Uma possível utilização de extract() é na importação de variáveis contidas num array associativo retornado pela função wddx_deserialize().

Exemplo 1. Exemplo de extract()
`<?php /* Suponha que $var_array é um array retornado pela função wddx_deserialize */ $tamanho = "grande"; $var_array = array ("cor" => "azul", "tamanho" => "medio", "forma" => "esfera"); extract ($var_array, EXTR_PREFIX_SAME, "wddx"); print "$cor, $tamanho, $forma, $wddx_tamanho\n"; ?>`
O exemplo acima produziria:
    azul, grande, esfera, medio

O `$tamanho` não foi sobrescrito, porque nós especificamos `EXTR_PREFIX_SAME`, o que resultou na criação da variável `$wddx_tamanho`. Se `EXTR_SKIP` fosse utilizado, então $wddx_tamanho não seria criada. `EXTR_OVERWRITE` teria feito com que `$tamanho` tivesse o valor "medio", e `EXTR_PREFIX_ALL` resultaria em novas variáveis com os nomes `$wddx_cor`, `$wddx_tamanho`, e `$wddx_forma`.

Você deve usar um array associativo, um array indexado numericamente não produzirá resultados a menos que você use `EXTR_PREFIX_ALL` ou `EXTR_PREFIX_INVALID`.

Veja também compact().

Anterior | Principal | Próxima
end | Acima | in_array