Import variables into the current symbol table from an array

end
in_array
Array Functions
PHP Manual

# extract

(PHP 4, PHP 5)

extract — 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].

### See Also

- compact() - Create array containing variables and their values
- list() - Assign variables as if they were an array

end
in_array
Array Functions
PHP Manual