extract
(PHP 4, PHP 5, PHP 7, PHP 8)
extract — Import variables into the current symbol table from an array
Description
&$array, int $flags = EXTR_OVERWRITE, string $prefix = ""): intImport variables from an array into the current symbol table.
Checks each key to see whether it has a valid variable name. It also checks for collisions with existing variables in the symbol table.
Parameters
-
array -
An associative array. This function treats keys as variable names and values as variable values. For each key/value pair it will create a variable in the current symbol table, subject to
flagsandprefixparameters.You must use an associative array; a numerically indexed array will not produce results unless you use
EXTR_PREFIX_ALLorEXTR_PREFIX_INVALID. -
flags -
The way invalid/numeric keys and collisions are treated is determined by the extraction
flags. It can be one of the following values:-
EXTR_OVERWRITE - If there is a collision, overwrite the existing variable.
-
EXTR_SKIP - If there is a collision, don't overwrite the existing variable.
-
EXTR_PREFIX_SAME -
If there is a collision, prefix the variable name with
prefix. -
EXTR_PREFIX_ALL -
Prefix all variable names with
prefix. -
EXTR_PREFIX_INVALID -
Only prefix invalid/numeric variable names with
prefix. -
EXTR_IF_EXISTS - Only overwrite the variable if it already exists in the current symbol table, otherwise do nothing. This is useful for defining a list of valid variables and then extracting only those variables you have defined out of $_REQUEST, for example.
-
EXTR_PREFIX_IF_EXISTS - Only create prefixed variable names if the non-prefixed version of the same variable exists in the current symbol table.
-
EXTR_REFS -
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the
arrayparameter. You can use this flag on its own or combine it with any other flag by OR'ing theflags.
If
flagsis not specified, it is assumed to beEXTR_OVERWRITE. -
-
prefix -
Note that
prefixis only required ifflagsisEXTR_PREFIX_SAME,EXTR_PREFIX_ALL,EXTR_PREFIX_INVALIDorEXTR_PREFIX_IF_EXISTS. If the prefixed result is not a valid variable name, it is not imported into the symbol table. Prefixes are automatically separated from the array key by an underscore character.
Return Values
Returns the number of variables successfully imported into the symbol table.
Examples
Example #1 extract() example
A possible use for extract() is to import into the symbol table variables contained in an associative array returned by wddx_deserialize().
<?php
/* Suppose that $var_array is an array returned from
wddx_deserialize */
$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";
?>
The above example will output:
blue, large, sphere, medium
The $size wasn't overwritten because we specified
EXTR_PREFIX_SAME, which resulted in
$wddx_size being created. If EXTR_SKIP was
specified, then $wddx_size wouldn't even have been created.
EXTR_OVERWRITE would have caused $size to have
value "medium", and EXTR_PREFIX_ALL would result in new variables
being named $wddx_color,
$wddx_size, and
$wddx_shape.
Notes
Do not use extract() on untrusted data, like
user input
(i.e. $_GET, $_FILES, etc.).
If you do, make sure you use one of the non-overwriting
flags values such as
EXTR_SKIP and be aware that you should extract
in the same order that's defined in
variables_order within the
php.ini.
