extract

    (PHP 4, PHP 5, PHP 7, PHP 8)

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

    Descrição

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

    Importar variáveis a partir de um array para a tabela de símbolos corrente.

    Verifica cada chave se ela tem nome de variável válido. Também verifica por colisões com já existente variáveis na tabela de símbolos.

    Aviso

    Não use extract() em dados inseguros, como informações externas (e.g. $_GET, $_FILES).

    Parâmetros

    array

    Um array associativo. Esta função trata chaves como nome de variáveis e valores com os valores da variáveis. Para cada par chave/valor ela cria uma variável na atual tabela de símbolo, seguindo os parâmetros flags e prefix.

    Você precisa usar um array associativo, um array numericamente indexado não irá produzir resultado até que você use EXTR_PREFIX_ALL ou EXTR_PREFIX_INVALID.

    flags

    A forma como inválida/chaves numéricas e colisões são tratadas é determinada por flags. Pode ser um dos 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.
    EXTR_PREFIX_INVALID
    Adiciona um prefixo definido por prefix apenas para variáveis como nomes inválidos ou numéricos.
    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.
    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.
    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 array. Essa opção pode ser usada sozinha ou em conjunto com as outras usando o operador 'ou' em flags.

    Se flags não for especificado, é assumido o valor EXTR_OVERWRITE.

    prefix

    Note que prefix só é necessário se flags 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. Prefixos são automaticamente separados da chave do array pelo caractere underscore.

    Valor Retornado

    Retorna o número de variáveis importadas com sucesso para a tabela de símbolo.

    Exemplos

    Exemplo #1 Exemplo da extract()

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

    <?php



    $size = "large";
    $var_array = array("color" => "blue",
    "size" => "medium",
    "shape" => "sphere");
    extract($var_array, EXTR_PREFIX_SAME, "wddx");

    echo     "$color, $size, $shape, $wddx_size\n";

    ?>

    O exemplo acima produzirá:

    blue, large, sphere, medium

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

    Notas

    Aviso

    Não use extract() em dados não confiáveis, como entrada de usuário (por exemplo, $_GET, $_FILES, etc.). Se usar, certifique-se de que está usando um dos valores de flags que não fazem sobrescrita como EXTR_SKIP e tenha cuidado para que extraia na mesma ordem que é definida em variables_order no php.ini.

    Veja Também

    • compact() - Cria um array contendo variáveis e seus valores
    • list() - Cria variáveis como se fossem arrays
    To Top