Import variables from an array into the current symbol table.
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.
Parameters
var_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
extract_type
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.
extract_type
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
.
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 var_array
parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
extract_type
.
If extract_type
is not specified, it is
assumed to be EXTR_OVERWRITE.
prefix
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. 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.
ChangeLog
Version
Description
4.3.0
EXTR_REFS was added.
4.2.0
EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS
were added.
4.0.5
This function now returns the number of variables extracted.
EXTR_PREFIX_INVALID was added.
EXTR_PREFIX_ALL includes numeric variables as well.
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 */
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
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
in the same order that's defined in
variables_order within the
php.ini.
Load balance : Server 03
