(PHP 4, PHP 5, PHP 7, PHP 8)
extract — Import variables into the current symbol table from an array
&$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.
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
flags
and prefix
parameters.
You must use an associative array; a numerically indexed array
will not produce results unless you use EXTR_PREFIX_ALL
or
EXTR_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
EXTR_SKIP
EXTR_PREFIX_SAME
prefix
.
EXTR_PREFIX_ALL
prefix
.
EXTR_PREFIX_INVALID
prefix
.
EXTR_IF_EXISTS
EXTR_PREFIX_IF_EXISTS
EXTR_REFS
array
parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
flags
.
If flags
is not specified, it is
assumed to be EXTR_OVERWRITE
.
prefix
Note that prefix
is only required if
flags
is EXTR_PREFIX_SAME
,
EXTR_PREFIX_ALL
, EXTR_PREFIX_INVALID
or EXTR_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.
Returns the number of variables successfully imported into the symbol table.
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.
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.