extract

說明

int extract ( array var_array [, int extract_type [, string prefix]] )

本函數用來將變量從陣列中匯入到現用的的符號表中。接受結合陣列 var_array 作為參數並將鍵名當作變量名，值作為變量的值。對每個鍵／值對都會在現用的的符號表中建立變量，並受到 extract_type 和 prefix 參數的影響。

注: 自版本 4.0.5 起本函數返回被提取的變量數目。

注: EXTR_IF_EXISTS 和 EXTR_PREFIX_IF_EXISTS 是版本 4.2.0 中引進的。

注: EXTR_REFS 是版本 4.3.0 中引進的。

extract() 檢查每個鍵名看是否可以作為一個合法的變量名，同時也檢查和符號表中已有的變量名的衝突。對待非法／數字和衝突的鍵名的方法將根據 extract_type 參數決定。可以是以下值之一：

EXTR_OVERWRITE: 若果有衝突，覆蓋已有的變量。
EXTR_SKIP: 若果有衝突，不覆蓋已有的變量。
EXTR_PREFIX_SAME: 若果有衝突，在變量名前加上前綴 prefix。
EXTR_PREFIX_ALL: 給所有變量名加上前綴 prefix。自 PHP 4.0.5 起這也內含了對數字索引的處理。
EXTR_PREFIX_INVALID: 僅在非法／數字的變量名前加上前綴 prefix。本旗標是 PHP 4.0.5 新加的。
EXTR_IF_EXISTS: 僅在現用的符號表中已有同名變量時，覆蓋它們的值。其它的都不處理。可以用在已經定義了一組合法的變量，然後要從一個陣列例如 $_REQUEST 中提取值覆蓋這些變量的場合。本旗標是 PHP 4.2.0 新加的。
EXTR_PREFIX_IF_EXISTS: 僅在現用的符號表中已有同名變量時，建立附加了前綴的變量名，其它的都不處理。本旗標是 PHP 4.2.0 新加的。
EXTR_REFS: 將變量作為引用提取。這有力地顯示了匯入的變量仍然引用了 var_array 參數的值。可以單獨使用這個標誌或是在 extract_type 中用 OR 與其它任何標誌結合使用。本旗標是 PHP 4.3.0 新加的。

若果沒有指定 extract_type，則被假定為 EXTR_OVERWRITE。

注意 prefix 僅在 extract_type 的值是 EXTR_PREFIX_SAME，EXTR_PREFIX_ALL，EXTR_PREFIX_INVALID 或 EXTR_PREFIX_IF_EXISTS 時需要。若果附加了前綴後的結果不是合法的變量名，將不會匯入到符號表中。前綴和陣列鍵名之間會自動加上一個下劃線。

extract() 返回成功匯入到符號表中的變量數目。

警示

不要對不能信任的資料使用 extract()，例如會員的輸入（$_GET，...）。若果這樣做，舉例說，要臨時運行依賴於 register_globals 的老代碼，要確保使用不會覆蓋的 extract_type 值，例如 EXTR_SKIP，並且要留意應該按照 php.ini 中由 variables_order 定義的順序來提取。

extract() 的一種可能用法是將 wddx_deserialize() 返回的結合陣列中的內容匯入到符號表變量中去。

例子 1. extract() 例子
<?php /* 假定 $var_array 是 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"; ?>
上例將輸出：
blue, large, sphere, medium

$size 沒有被覆蓋，因為指定了 EXTR_PREFIX_SAME，這使得 $wddx_size 被建立。若果指定了 EXTR_SKIP，則 $wddx_size 也不會被建立。EXTR_OVERWRITE 將使 $size 的值為「medium」，EXTR_PREFIX_ALL 將建立新變量 $wddx_color，$wddx_size 和 $wddx_shape。

必須使用關聯陣列，數字索引的陣列將不會產生結果，除非用了 EXTR_PREFIX_ALL 或是 EXTR_PREFIX_INVALID。

參見 compact()。