EXTRACT(3)								 1								EXTRACT(3)

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

SYNOPSIS

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

DESCRIPTION

	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

	      o $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.

	      o $flags
		-  The	way invalid/numeric keys and collisions are treated is determined by the extraction $flags. It can be one of the following
		values:

		     o EXTR_OVERWRITE - If there is a collision, overwrite the existing variable.

		     o EXTR_SKIP - If there is a collision, don't overwrite the existing variable.

		     o EXTR_PREFIX_SAME -If there is a collision, prefix the variable name with $prefix.

		     o EXTR_PREFIX_ALL - Prefix all variable names with $prefix.

		     o EXTR_PREFIX_INVALID - Only prefix invalid/numeric variable names with $prefix.

		     o 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.

		     o EXTR_PREFIX_IF_EXISTS - Only create prefixed variable names if the non-prefixed version of the same variable exists in  the
		       current symbol table.

		     o 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.

	      o $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  sepa-
		rated from the array key by an underscore character.

RETURN VALUES

	Returns the number of variables successfully imported into the symbol table.

EXAMPLES

       Example #1

	      extract(3) example

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

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

	      ?>

	      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(3) 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(3) 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(3) 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(3) 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 $test-
	      file['tmp_name'] as $testfile[0].

SEE ALSO

       compact(3), list(3).

PHP Documentation Group 														EXTRACT(3)