PHP Manual
PrevNext

extract

(PHP 3>= 3.0.7, PHP 4 >= 4.0b1)

extract --  Import variables into the 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 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: Since version 4.0.5 this function returns the number of variables extracted.

extract() checks each key to see whether if constitutes a valid variable name and also for collisions with existing variables in the symbol table. The way invalid/numeric keys and collisions are treated is determined by 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. Since PHP 4.0.5 this includes numeric ones as well.

EXTR_PREFIX_INVALID

Only prefix invalid/numeric variable names with prefix. This flag has been added in PHP 4.0.5.

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, or EXTR_PREFIX_INVALID. 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 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, becaus 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 cause $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.

See also: compact().

PrevHomeNext
endUpin_array