Description
int
extract ( array var_array [, int extract_type [, string prefix]])
This function is used to import variables from an array into the
current symbol table. It takes an associative array
var_array and 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
extract_type and
prefix parameters.
Note:
Beginning with version 4.0.5, this function returns the number of
variables extracted.
Note:
EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS were introduced in version 4.2.0.
Note:
EXTR_REFS was introduced in version 4.3.0.
extract() checks each key to see whether it
has a valid variable name. It also checks for collisions with
existing variables in the symbol table. The way invalid/numeric
keys and collisions are treated is determined by the
extract_type. 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. Beginning with PHP 4.0.5, this includes
numeric variables as well.
- EXTR_PREFIX_INVALID
Only prefix invalid/numeric variable names with
prefix. This flag was added in
PHP 4.0.5.
- 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. This flag was added in PHP 4.2.0.
- EXTR_PREFIX_IF_EXISTS
Only create prefixed variable names if the non-prefixed version
of the same variable exists in the current symbol table. This
flag was added in PHP 4.2.0.
- EXTR_REFS
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the var_array parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
extract_type. This flag was added in PHP
4.3.0.
If extract_type is not specified, it is
assumed to be EXTR_OVERWRITE.
Note that prefix is only required if
extract_type 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.
extract() returns the number of variables
successfully imported into the symbol table.
Warning |
Do not use extract() on untrusted data, like
user-input ($_GET, ...). If you do, for example, if you want to run old
code that relies on
register_globals
temporarily, make sure you use one of the non-overwriting
extract_type values such as
EXTR_SKIP and be aware that you should extract
$_SERVER, $_SESSION,
$_COOKIE, $_POST and
$_GET in that order.
|
A possible use for extract() is to import into the
symbol table variables contained in an associative array returned by
wddx_deserialize().
Example 1. extract() example
<?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 produce:
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.
You must use an associative array, a numerically indexed array
will not produce results unless you use EXTR_PREFIX_ALL or
EXTR_PREFIX_INVALID.
See also compact().