PHP Manual: Import variables into the current symbol table from an array

Description

int extract ( array &$array [, int $flags = EXTR_OVERWRITE [, string $prefix = NULL ]] )

Import 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 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: 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 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.

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 */

$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

Warning

Do not use extract on untrusted data, like user input (i.e. $_GET, $_FILES, etc.). 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 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.

Note:
If you have register_globals turned on and you use extract on $_FILES and specify EXTR_SKIP, you may be surprised at the results.

Warning
This is not recommended practice and is only documented here for completeness. The use of register_globals is deprecated and calling extract on untrusted data such as $_FILES is, as noted above, a potential security risk. If you encounter this issue, it means that you are using at least two poor coding practices.

<?php /* Suppose that $testfile is the name of a file upload input and that register_globals is turned on. */ var_dump($testfile); extract($_FILES, EXTR_SKIP); var_dump($testfile); var_dump($testfile['tmp_name']); ?>

You might expect to see something like the following:
string(14) "/tmp/phpgCCPX8"
array(5) {
  ["name"]=>
  string(10) "somefile.txt"
  ["type"]=>
  string(24) "application/octet-stream"
  ["tmp_name"]=>
  string(14) "/tmp/phpgCCPX8"
  ["error"]=>
  int(0)
  ["size"]=>
  int(4208)
}
string(14) "/tmp/phpgCCPX8"
However, you would instead see something like this:
string(14) "/tmp/phpgCCPX8"
string(14) "/tmp/phpgCCPX8"
string(1) "/"
This is due to the fact that since register_globals is turned on, $testfile already exists in the global scope when extract is called. And since EXTR_SKIP is specified, $testfile is not overwritten with the contents of the $_FILES array so $testfile remains a string. Because strings may be accessed using array syntax and the non-numeric string tmp_name is interpreted as 0, PHP sees $testfile['tmp_name'] as $testfile[0].

extract