extract

Manual de PHP
Anterior		Siguiente

Descripción

void extract ( array matriz_vars [, int tipo_extraccion [, string prefijo]] )

Esta función se utiliza para importar variables desde una matriz a la tabla de símbolos actual. Toma la matriz asoiativa matriz_vars y trata las claves como nombres de variable y los valores como los valores de éstas. Para cada par clave/valor creará una variable en la tabla de símbolos actual, sujeto a los parámetros tipo_extraccion y prefijo.

Nota: Empezando de la versión 4.0.5, esta función regresa el número de variables extraídas.

Nota: EXTR_IF_EXISTS y EXTR_PREFIX_IF_EXISTS fueron introducidas en la versión 4.2.0.

Nota: EXTR_REFS fue introducida en la versión 4.3.0.

extract() controla las colisiones con las variables que ya existen. La forma de tratar éstas se determina por el tipo_extraccion. Puede tener únicamente uno de los siguientes valores:

EXTR_OVERWRITE: Si hay colisión, sobreescribe la variable existente.
EXTR_SKIP: Si hay colisión, no sobreescribas la variable existente.
EXTR_PREFIX_SAME: Si hay una colisión, añade el prefijo a la nueva variable.
EXTR_PREFIX_ALL: Añade el prefijo a todas las variables.
EXTR_PREFIX_INVALID: Solo agrega el prefijo a nombres de variables invalidas/numéricas. Este fue agregado en PHP 4.0.5.
EXTR_IF_EXISTS: Solo sobreescribe la variable si ya existe en la tabla de símbolos actual, de otra manera no hace nada. Esto es útil para definir una lista de variables validas y entonces extraer solo aquellas variables que esten definidas fuera de $_REQUEST por ejemplo. Esta bandera fue agregada en PHP 4.2.0.
EXTR_PREFIX_IF_EXISTS: Solo crea los nombres de variables con el prefijo si la versión de la variable sin prefijo existe en la tabla de símbolos. Esta bandera fue agregada en PHP 4.2.0.
EXTR_REFS: Extrae las variables como referencias. Esto efectivamente significa que los valores de las variables importadas están aún referenciando a los valores del parámetro matriz_var. Puede usar esta bandera por sí sola o combinada con cualquier otra bandera haciendo (OR) el parámetro tipo_extraccion. Esta bandera fue agregada en PHP 4.3.0.

Si no se especifica tipo_extraccion, se asume que vale EXTR_OVERWRITE.

Nótese que el prefijo sólo se necesita si tipo_extraccion vale EXTR_PREFIX_SAME, EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID o EXTR_PREFIX_IF_EXISTS. Si el resultado con prefijo no es un nombre de variable valido, no es importado en la tabla de símbolos.

extract() regresa el número de variables exitosamente importadas en la tabla de símbolos.

Aviso

No use extract() en datos no confiables, como entradas de usuario ($_GET, ...). pero si lo hace, por ejemplo, si quiere correr codigo anterior que confía temporalmente en register_globals, asegurese de que usa una de los valores de no-sobreescribir del parámetro tipo_extraccion tales como EXTR_SKIP y asegurese de extrar las variables $_SERVER, $_SESSION, $_COOKIE, $_POST y $_GET ese orden.

Un uso posible para extract sería importar en la tabla de símbolos las variables contenidas en la matriz asociativa que devuelve wddx_deserialize().

Ejemplo 1. Ejemplo de extract()
<?php /* Suponemos que $matriz_var es una matriz devuelta por wddx_deserialize */ $tamano = "grande"; $matriz_var = array ("color" => "azul", "tamano" => "media", "forma" => "esfera"); extract ($matriz_var, EXTR_PREFIX_SAME, "wddx"); print "$color, $tamano, $forma, $wddx_tamano\n"; ?>
El resultado del ejemplo seria:
azul, grande, esfera, media

La variable $tamano no fue sobreescrita porque especificamos EXTR_PREFIX_SAME, que provocó la creación de $wddx_tamano. Si se hubiera especificado EXTR_SKIP, $wddx_tamano ni siquiera habría sido creada. EXTR_OVERWRITE habría provocado que $tamano tuviera el valor "media", y EXTR_PREFIX_ALL habría provocado que aparecieran nuevas variables llamadas $wddx_color, $wddx_tamano, y $wddx_forma.

Debe usar matrices asociativas, las matrices numéricamente indexadas no producirán resultados a menos que use EXTR_PREFIX_ALL o EXTR_PREFIX_INVALID.

Vea también compact().