(PHP 3 >= 3.0.7, PHP 4, PHP 5)
extract -- Importa variáveis para a tabela de símbolos a partir de um array
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:
Se houver uma colisão, sobrescreve a variável existente.
Se houver uma colisão, não sobrescreve a variável existente.
Se houver uma colisão, adiciona um prefixo ao nome da
variável definido pelo argumento
prefix
.
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.
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.
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.
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.
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_OVERWRITEpor 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().
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().