Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Function Reference : Array Functions : extract

extract

Import variables into the current symbol table from an array (PHP 4, PHP 5)
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 were 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. Prefixes are automatically separated from the array key by an underscore character.

extract() returns the number of variables successfully imported into the symbol table.

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.

A possible use for extract() is to import into the symbol table variables contained in an associative array returned by wddx_deserialize().

Example 305. 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");

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.

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().

Related Examples ( Source code ) » extract






Code Examples / Notes » extract

22-feb-2005 03:31

To make this perfectly clear (hopefully), an underscore is always added when the string is prefixed.
extract(array("color" => "blue"),EXTR_PREFIX_ALL,'');// note: prefix is empty
is the same as
$color='_blue';


nicolas zeh

This function provides exactly the same functionality as extract except that a parameter was added defining the extract target.
This function can be used if your PHP installation does not support the required Flags or more important if you would like to extract arrays to another destination as to $GLOBALS, i.e. other arrays or objects.
The only difference to extract is that extract_to moves the array pointer of $arr to the end as $arr is passed by reference to support the EXTR_REFS flag.
<?php
if( !defined('EXTR_PREFIX_ALL') ) define('EXTR_PREFIX_ALL', 3);
if( !defined('EXTR_PREFIX_INVALID') ) define('EXTR_PREFIX_INVALID', 4);
if( !defined('EXTR_IF_EXISTS') ) define('EXTR_IF_EXISTS', 5);
if( !defined('EXTR_PREFIX_IF_EXISTS') ) define('EXTR_PREFIX_IF_EXISTS', 6);
if( !defined('EXTR_REFS') ) define('EXTR_REFS', 256);


function extract_to( &$arr, &$to, $type=EXTR_OVERWRITE, $prefix=false ){

if( !is_array( $arr ) ) return trigger_error("extract_to(): First argument should be an array", E_USER_WARNING );

if( is_array( $to ) ) $t=0;
else if( is_object( $to ) ) $t=1;
else return trigger_error("extract_to(): Second argument should be an array or object", E_USER_WARNING );

if( $type==EXTR_PREFIX_SAME || $type==EXTR_PREFIX_ALL || $type==EXTR_PREFIX_INVALID || $type==EXTR_PREFIX_IF_EXISTS )
if( $prefix===false ) return trigger_error("extract_to(): Prefix expected to be specified", E_USER_WARNING );
else $prefix .= '_';

$i=0;
foreach( $arr as $key=>$val ){

$nkey = $key;
$isset = $t==1 ? isset( $to[$key] ) : isset( $to->$key );

if( ( $type==EXTR_SKIP && $isset )
|| ( $type==EXTR_IF_EXISTS && !$isset ) )
continue;

else if( ( $type==EXTR_PREFIX_SAME && $isset )
|| ( $type==EXTR_PREFIX_ALL )
|| ( $type==EXTR_PREFIX_INVALID && !preg_match( '#^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$#', $key ) ) )
$nkey = $prefix.$key;

else if( $type==EXTR_PREFIX_IF_EXISTS )
if( $isset ) $nkey = $prefix.$key;
else continue;
if( !preg_match( '#^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$#', $nkey ) ) continue;

if( $t==1 )
if( $type & EXTR_REFS ) $to->$nkey = &$arr[$key];
else $to->$nkey = $val;
else
if( $type & EXTR_REFS ) $to[$nkey] = &$arr[$key];
else $to[$nkey] = $val;

$i++;
}

return $i;
}

// e.g.:
extract_to( $myarray, $myobject, EXTR_IF_EXISTS );
?>


michael newton

They say "If the result is not a valid variable name, it is not imported into the symbol table."
What they should say is that if _any_ of the results have invalid names, _none_ of the variables get extracted.
Under 4.3.10 on Windows 2000, I was pulling some mySQL records, but needed to convert two fields into IP addresses:
<?
extract(mysql_fetch_assoc(mysql_query('SELECT * FROM foo')));
extract(mysql_fetch_assoc(mysql_query('SELECT INET_NTOA(bar) AS bar, INET_NTOA(baz) FROM foo')));
?>
I had forgotten the second AS modifier in the SQL query.  Because it couldn't extract a variable called INET_NTOA(baz) into the symbol table, it didn't do either of them.
(BTW I don't normally stack functions up like that!  Just to make a short example!)


kake26

The following is a neat use for extract to store and manipulate large amounts of form data from. I basically loop through the $_POST and implode it seperating the key and value pairs by a space. Then store it in a db, the reversing function basically explodes the string to a array. Then converts the indexed array to a associative array then uses extract to seal the deal and make it easily available within a program. My main reason for sharing these are the fact I make some big web applications that store allot of forum data in a DB and these functions make it very easy to quickly and easily store and recall the data. I've contributed it because I spent many hours creating this code and recall going "I wish someone had previously submitted it to the page notes". Would have saved me allot of time and agony and I'm sure I'm not the only person that could really benefit from it, so I decided to share.
<?php
$stack = array();
foreach ($_POST as $key => $value) {
array_push($stack, $key, $value);
}
// store it
$block = implode(" ",$stack); // yeilds a space delimited string
// insert query to store string in DB here, like the one below
$query = "INSERT INTO `sometable` VALUES('".$seluser."','".addslashes($block)."');";
$result = mysql_query($query) or die("Query failed for block insert: " . mysql_error());
// note $seluser in my case is a user ID associated with that block
// in one of my web apps
?>
The nice thing is with the above we can quickly create a string of key and value pairs from the data the script got. Without really caring what their names are. You know how if register globals are on you say $someformvar rather than $_POST["someformvar"]; , basically the code below reads this previous created block returns it to that state. Sort of like presistant register globals.
<?php
// insert query to grab the previously stored string here
$query = "SELECT * FROM `sometable` WHERE `blockid` = '".addslashes($bid)."';";
$result = mysql_query($query) or die("Query failed read: " . mysql_error());
$sql = mysql_fetch_array($result, MYSQL_ASSOC);
$array = eplode(" ",$sql["data"]);
for ($i = 0; $i < sizeof($array); $i+=2) {
$myassoc[$array[$i]] = isset($array[$i+1])?$array[$i+1]:NULL;
}
extract($myassoc, EXTR_OVERWRITE);
// now you're key and value pairs from $_POST have been restored
// instead of $_POST
?>


csaba

Sometimes you may want to extract only a named subset of the key/value pairs in an array.  This keeps things more orderly and could prevent an unrelated variable from getting clobbered from an errant key.  For example,
$things = 'unsaid';
$REQUEST = array(He=>This, said=>1, my=>is, info=>2, had=>a,
                very=>3, important=>test, things=>4);
$aVarToExtract = array(my, important, info);
extract (array_intersect_key ($REQUEST, array_flip($aVarToExtract)));
will extract
$my = 'is';
$important = 'test';
$info = 2;
but will leave certain
$things = 'unsaid'
Csaba Gabor from Vienna
NB.  Of course the composite request coming in from a web page is in $_REQUEST.


ktwombley

It's really easy to open gaping security holes using extract() on $_REQUEST, $_GET, etc. You have to be really sure of what you're doing, and use the proper flags on extract() to avoid clobbering important variables.
For instance, the submission by kake26 at gmail dot com will not only perfectly emulate register globals (that's bad), but it'll store it in a database and recall the same variables every time the script runs (essentially allowing an attacker to attack your script every time it runs via one attack). Oops!
To fix it, you'd have to get creative with flags. Maybe you could use EXTR_PREFIX_ALL instead of EXTR_OVERWRITE, for example. Of course, you should also sanitize the form elements to ensure there's no php code in them, and also to make sure any very important variables aren't in the form data. (like the classic $is_admin = true attack)


aaron stone

If you are working porting an older application, and taking the advice above, extracting only _SERVER, _SESSING, _COOKIE, _POST, _GET, you have forgotten to extract _FILES. Putting _FILES last and using EXTR_SKIP doesn't work because the name of the file upload box is already set as a variable containing only the temporary name of the uploaded file from one of the earlier extracts (I haven't tested to see which one specifically, however). A workaround is to put _FILES last and use EXTR_OVERWRITE. This allows extract to replace that temp-name-only variable with the full array of file upload information.

dutchdavey

I would draw your attention to the user note at the very end of this page regarding PREFIXES. The user points out that php adds a '_' to your prefixes.

pg dot perfection

Here is a little example of how an extraction method should look like when it needs to work recursive (work on nested_arrays too)...
Note that this is only an example, it can be done more easily, and more advanced too.
<?php
/**
* A nested version of the extract () function.
*
* @param array $array The array which to extract the variables from
* @param int $type The type to use to overwrite (follows the same as extract () on PHP 5.0.3
* @param string $prefix The prefix to be used for a variable when necessary
*/
function extract_nested (&$array, $type = EXTR_OVERWRITE, $prefix = '')
{
/**
*  Is the array really an array?
*/
if (!is_array ($array))
{
return trigger_error ('extract_nested (): First argument should be an array', E_USER_WARNING);
}
/**
*  If the prefix is set, check if the prefix matches an acceptable regex pattern
* (the one used for variables)
*/
if (!empty ($prefix) && !preg_match ('#^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$#', $prefix))
{
return trigger_error ('extract_nested (): Third argument should start with a letter or an underscore', E_USER_WARNING);
}
/**
* Check if a prefix is necessary. If so and it is empty return an error.
*/
if (($type == EXTR_PREFIX_SAME || $type == EXTR_PREFIX_ALL || $type == EXTR_PREFIX_IF_EXISTS) && empty ($prefix))
{
return trigger_error ('extract_nested (): Prefix expected to be specified', E_USER_WARNING);
}
/**
* Make sure the prefix is oke
*/
$prefix = $prefix . '_';
/**
*  Loop thru the array
*/
foreach ($array as $key => $val)
{
/**
*  If the key isn't an array extract it as we need to do
*/
if (!is_array ($array[$key]))
{
switch ($type)
{
default:
case EXTR_OVERWRITE:
$GLOBALS[$key] = $val;
break;
case EXTR_SKIP:
$GLOBALS[$key] = isset ($GLOBALS[$key]) ? $GLOBALS[$key] : $val;
break;
case EXTR_PREFIX_SAME:
if (isset ($GLOBALS[$key]))
{
$GLOBALS[$prefix . $key] = $val;
}
else
{
$GLOBALS[$key] = $val;
}
break;
case EXTR_PREFIX_ALL:
$GLOBALS[$prefix . $key] = $val;
break;
case EXTR_PREFIX_INVALID:
if (!preg_match ('#^[a-zA-Z_\x7f-\xff]$#', $key{0}))
{
$GLOBALS[$prefix . $key] = $val;
}
else
{
$GLOBALS[$key] = $val;
}
break;
case EXTR_IF_EXISTS:
if (isset ($GLOBALS[$key]))
{
$GLOBALS[$key] = $val;
}
break;
case EXTR_PREFIX_IF_EXISTS:
if (isset ($GLOBALS[$key]))
{
$GLOBALS[$prefix . $key] = $val;
}
break;
case EXTR_REFS:
$GLOBALS[$key] =& $array[$key];
break;
}
}
/**
*  The key is an array... use the function on that index
*/
else
{
extract_nested ($array[$key], $type, $prefix);
}
}
}
?>


dan o'donnell

Following up on ktwombley at gmail dot com's post:
Presumably one easy way of dealing with this security issue is to use the EXTR_IF_EXISTS flag and make sure
a) your define acceptable input variables beforehand (i.e. as empty variables)
b) Sanitise any user input to avoid unacceptable variable content.
If you do these two things, then I'm not sure I see the difference between extract($_REQUEST,EXTR_IF_EXISTS); and assigning each of the variables by hand.
I'm not talking here about the idea of storing the variables in a database, just the immediately necessary steps to allow you to use extract on REQUEST arrays with relative safety.


moslehigmailc0m

Experimentally I found that calling extract() also shows the number of keys if the key is set and is not numeric ! Maybe there was a better definition than mine  . Please have a look to this scripts :
<?PHP
$var["i"] = "a";
$var["j"] = "b";
$var["k"] = 1;
echo extract($var); // returns 3
?>
<?PHP
$var2["i"] = "a";
$var2[2] = "b";
$var2[] = 1;
echo extract($var2); // returns 1
?>
(Arash Moslehi)


adam monsen
As shown in the example, if your 'prefix' is used, a single underscore is added to the name of the extracted variable. Meaning, a prefix of 'p' becomes a prefix of 'p_', so 'blarg' prefixed would be 'p_blarg'.
If you're not sure what variables you've created through extraction, you can call get_defined_vars() to see all defined variables in the current scope.


owk dot ch199_ph

And if you want with PHP 5 an easy way to extract $V by reference, try this :
<?php
   foreach ($V as $k => &$v) {
       $$k =& $v;
   }
?>
It can be used to create special kind of "free args" functions that let you choose when you call them the way you send variables, and which ones. They are moreover very fast to call thanks to references :
<?php
   function free_args (&$V) {
       foreach ($V as $k => &$v) {
           $$k =& $v;
       }
       unset ($k);  unset ($v);  unset ($V);
       // be careful that if you need to extract $k, $v or $V variables you should find other names for them in the lines above (ie. $__k, $__v and $__V)
   }
   $huge_text = '...';
   $a = array ('arg1' => 'val1', 'arg2' => &$huge_text); // in this call, only $arg2 will be a true reference in the function
   free_args ($a);
?>
Be warned that you can't write : "<?php free_args (array ('arg1' => 'val1')); ?>" because the array can't be referenced by the function, as it's not yet created when the function starts.


anon

A warning about extract() and null values.
This might be an actual Zend2 Engine bug, but it's bad programming practice, so I'm sharing it here instead.
I often work in envrionments where E_STRICT (which would prevent errors like this) isn't on, and I don't have access to change it. I also use a very simple template class that in a nutshell works like this:
$t = new Template('somefile.php');
$t->title = $title;
$t->body = $body;
$t->display();
display() more or less looks like this:
function display(){
   extract(get_object_vars($this),EXTR_REFS);
   ob_start(); include $this->templateFileName;
   return ob_get_clean();
}
If any of the assigned values are null (let's say that in this case $title wasn't initialized above) it causes the engine to do all sorts of incredibly whacky stuff like certifiably lose track of variables in an incredibly inconsistent way. I traced the problem down to the fact that it's using the EXTR_REFS flag. I assume that in PHP's internal variable storage or reference counting mechanism, that trying to extract null references makes it lose track or count of something or rather.
In a nutshell, if you start getting wierd behavior when using extract() make sure that the array or object you are trying to get variables out of doesn't contain null keys or values!


Change Language


Follow Navioo On Twitter
array_change_key_case
array_chunk
array_combine
array_count_values
array_diff_assoc
array_diff_key
array_diff_uassoc
array_diff_ukey
array_diff
array_fill_keys
array_fill
array_filter
array_flip
array_intersect_assoc
array_intersect_key
array_intersect_uassoc
array_intersect_ukey
array_intersect
array_key_exists
array_keys
array_map
array_merge_recursive
array_merge
array_multisort
array_pad
array_pop
array_product
array_push
array_rand
array_reduce
array_reverse
array_search
array_shift
array_slice
array_splice
array_sum
array_udiff_assoc
array_udiff_uassoc
array_udiff
array_uintersect_assoc
array_uintersect_uassoc
array_uintersect
array_unique
array_unshift
array_values
array_walk_recursive
array_walk
array
arsort
asort
compact
count
current
each
end
extract
in_array
key
krsort
ksort
list
natcasesort
natsort
next
pos
prev
range
reset
rsort
shuffle
sizeof
sort
uasort
uksort
usort
eXTReMe Tracker