الدالة extract()‎ في PHP

(PHP 4, PHP 5, PHP 7)

تستخلص الدالة extract()‎ المتغيرات من مصفوفة ما وتدخلها في جدول الرموز الحالي.

الوصف

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

تستخلص الدالة المتغيرات من مصفوفة ما وتدخلها في جدول الرموز الحالي.

وتتحقق من كل مفتاح لمعرفة ما إذا كان له اسم متغير صالح. كما تتحقق من التضاربات مع المتغيرات الموجودة في جدول الرموز.

تحذير: لا تستخدم الدالة extract()‎ مع بيانات غير موثوقة، مثل إدخالات المستخدم (على سبيل المثال ‎$_GET و ‎$_FILES).

المعاملات

array

مصفوفة ترابطية. تعامل هذه الدالةُ المفاتيحَ كأسماء متغيرات وتعامل القيم كقيم لتلك المتغيرات. لكلٍ من المفتاح والقيمة، تنشئ الدالة متغيرًا في جدول الرموز الحالي، مع مراعاة الرايات flags والبادئة prefix.

يجب استخدام مصفوفة ترابطية؛ إذ لا تنتج مصفوفة مفهرسة عدديًا نتائجَ إلا إذا أُستُخدِمت الرايتان EXTR_PREFIX_ALL أو EXTR_PREFIX_INVALID.

flags

تُحدد طريقة التعامل مع المفاتيح غير الصالحة أو الرقمية والتضاربات عن طريق استخراج الرايات flags. والتي يمكن أن تتخذ أحد القيم التالية:

• EXTR_OVERWRITE: الكتابة فوق المتغير الموجود إذا كان هناك تضارب.
• EXTR_SKIP: عدم الكتابة فوق المتغير الموجود إذا كان هناك تضارب.
• EXTR_PREFIX_SAME: تَصَدُّر اسم المتغير بالبادئة prefix إذا كان هناك تضارب.
• EXTR_PREFIX_ALL: تَصَدُّر جميع اسماء المتغيرات بالبادئة prefix.
• EXTR_PREFIX_INVALID: تَصَدُّر اسم المتغير غير الصالح أو العددي بالبادئة prefix.
• EXTR_IF_EXISTS: الكتابة فوق المتغير فقط في حالة إذا كان موجودًا بالفعل في جدول الرموز الحالي، وإلا فلا يحدث شيء. يفيد ذلك، على سبيل المثال، في تحديد قائمة المتغيرات الصالحة ثم استخراج تلك المتغيرات التي عرّفتها فقط من ‎$_REQUEST.
• EXTR_PREFIX_IF_EXISTS: إنشاء أسماء المتغيرات مسبوقة بالبادئة فقط إذا كان الإصدار غير المسبوق بالبادئة من نفس المتغير موجودًا في جدول الرموز الحالي.
• EXTR_REFS: استخلاص المتغيرات كمراجع (references). الأمر الذي يعني أن قيم المتغيرات المستخلصة لا تزال تشير فعليًا إلى قيم معامل المصفوفة array. ويمكنك استخدام هذه الراية بمفردها أو دمجها مع أي راية أخرى باستخدام المعامل الثنائي OR.

إذا لم يُحدد المعامل flags، يُفترض بالقيمة EXTR_OVERWRITE.

prefix

لاحظ أن معامل البادئة prefix مطلوب فقط إذا كانت قيمة الراية flags هي EXTR_PREFIX_SAME ، EXTR_PREFIX_ALL أو EXTR_PREFIX_INVALID أو EXTR_PREFIX_IF_EXISTS. وإذا كانت النتيجة البادئة ليست اسم متغير صالح، فلن تستورد إلى جدول الرموز. تُفصل البادئات تلقائيًا عن مفتاح المصفوفة بواسطة حرف الشرطة السفلية "_".

القيم المعادة

تُعيد الدالة عدد المتغيرات التي استُخلصت بنجاح إلى جدول الرموز.

أمثلة

المثال 1: مثال على الدالة extract()‎

الاستخدام المحتمل للدالة extract()‎ هو استخلاص المتغيرات المتضمنة في مصفوفة ترابطية أُعيدت بواسطة الدالة wddx_deserialize()‎ إلى جدول الرموز.

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

?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

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.

ملاحظات

تحذير: لا تستخدم الدالة extract()‎ مع بيانات غير موثوقة، مثل إدخالات المستخدم (على سبيل المثال ‎$_GET و ‎$_FILES ...إلخ.). وإذا قمت بذلك، على سبيل المثال في حالة كنت تريد تشغيل التعليمات البرمجية القديمة التي تعتمد على register_globals مؤقتًا، فتأكد من استخدام إحدى قيم flags التي لا تسمح بالكتابة فوق المتغيرات الموجودة مسبقًا مثل EXTR_SKIP، لاحظ أنَّ استخراج القيم من المصفوفة سيكون بنفس الترتيب الذي عُرّف به في variables_order داخل php.ini.

ملاحظة: إذا كنت لا تزال تستعمل توجيهات register_globals وكانت قيد التشغيل، وإذا كنت تستخدم extract()‎ على المتغير ‎$_FILES وعينت الراية EXTR_SKIP، فقد تُفاجأ من النتائج.

تحذير: هذه ليست ممارسة مستحسنة ونذكرها فقط للتوثيق من أجل اكتمال المعلومة. لقد أهمل استخدام register_globals، ويُعد استخدام الدالة extract()‎ على بيانات غير موثوقة مثل ‎$_FILES من المخاطر الأمنية المحتملة كما هو موضح أعلاه. وإذا واجهتك هذه المشكلة، فهذا يعني أنك تستخدم ممارستين سيئتين للبرمجة على الأقل.

<?php
/* افترض أن testfile $ هو اسم إدخال إيداع ملف
  وأن register_globals قيد التشغيل. */
var_dump($testfile);
extract($_FILES, EXTR_SKIP);
var_dump($testfile);
var_dump($testfile['tmp_name']);
?>

قد تتوقع نتائج مثل ما يلي:

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"

ومع ذلك، يمكنك بدلاً من ذلك الحصول على مُخرج مثل هذا:

string(14) "/tmp/phpgCCPX8"
string(14) "/tmp/phpgCCPX8"
string(1) "/"

يرجع ذلك إلى حقيقة أنه منذ تشغيل register_globals، يوجد بالفعل المتغير testfile‎$ في النطاق العام عند استدعاء الدالة extract()‎. ولأنَّ الراية EXTR_SKIP مُحدّدة، فلن يُكتب فوق المتغير testfile‎$ مع محتويات المصفوفة ‎$_FILES بالتالي يبقى المتغير ‎$testfile يُخزِّن سلسلة نصية. ولمّا كان يمكن الوصول إلى السلاسل النصية باستخدام بناء جملة بناء المصفوفة ولأنَّ PHP تُفسر السلسلة غير الرقمية tmp_name على أنها 0، لذا سترى PHP المتغير ‎$testfile ['tmp_name']‎ كما لو أنَّه ‎$testfile‎ [0]‎.

انظر أيضًا

• الدالة compact()‎: إنشاء مصفوفة تحتوي على متغيرات وقيمها.
• الدالة list()‎: تعيين المتغيرات كما لو كانت تشكل مصفوفة.

مصادر

• صفحة الدالة extract‎‎ في توثيق PHP الرسمي.