PHP Manual
Prev |  | Next

# extract

(PHP 3>= 3.0.7, PHP 4 )

extract -- Import variables into the current symbol table from an array

## 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 was 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.

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");

    print "$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().

Prev | Home | Next
end | Up | in_array