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

(PHP 4, PHP 5, PHP 7)

تُعيّن الدالة list()‎‎‎ المتغيرات كما لو كانت تشكل مصفوفة.

الوصف

array list ( mixed $var1 [, mixed $... ] )

مثلما هو الحال مع الدالة array()‎‎‎، تمثل الدالة list()‎‎‎‎ بنيةً من بنى اللغة تُستخدم لتمثيل قائمة من المتغيرات في عملية واحدة، وليست دالةً عاديةً.

ملاحظة: تُستخدم الدالة list()‎‎‎‎ فقط مع المصفوفات الرقمية وتفترض فهارس رقمية تبدأ من 0.

تحذير: في PHP 5، تبدأ الدالة list()‎‎‎‎ بتعيين القيم بدءًا من أقصى اليمين. أما في PHP 7، فتبدأ من أقصى اليسار.

إذا كنت تستخدم متغيرات بسيطة، فلا داعي للقلق بشأن هذا الأمر. أما إذا كنت تستخدم مصفوفات باستخدام الفهارس، فعادة ما تتوقع أن يكون ترتيب الفهارس في المصفوفة هو نفسه الذي كتبته في الدالة list()‎‎‎ من اليسار إلى اليمين، وهو ما لا يحدث في PHP 5، إذ يتبع ترتيبًا عكسيًا.

وبشكل عام، من المستحسن تجنب الاعتماد على ترتيب معين للعمليات، لأنه قد يتغير مرة أخرى في المستقبل.

تحذير: تعديل المصفوفة أثناء تنفيذ list()‎‎‎ (على سبيل المثال باستخدام list ($a، $b) = $b) ينتج عنه سلوك غير معرف.

المعاملات

var1

المتغير المُدخل.

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

تُعيد الدالة المصفوفة المُعيّنة.

سجل التغييرات

الإصدار	الوصف
7.0.0	تغيير الترتيب الذي تُنفذ به عمليات التعيين فيه.
7.0.0	إلغاء السماح بإمكانية أن تكون تعبيرات الدالة list()‎‎‎ فارغة.
7.0.0	إلغاء إمكانية فك حزم السلاسل النصية.

أمثلة

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

<?php
$info = array('coffee', 'brown', 'caffeine');
// عرض قائمة جميع المتغيرات
list($drink, $color, $power) = $info;
echo "$drink is $color and $power makes it special.\n";
// عرض قائمة بعض المتغيرات
list($drink, , $power) = $info;
echo "$drink has $power.\n";
// أو دعنا نتخطى حتى المتغير الثالث فقط
list( , , $power) = $info;
echo "I need $power!\n";
// لا تعمل الدالة list()‎‎‎ مع السلاسل النصية
list ( $ bar ) = "abcde" ؛
var_dump($bar); // NULL
?>

المثال 2: مثال على الدالة list()‎‎‎‎

<table>
 <tr>
  <th>Employee name</th>
  <th>Salary</th>
 </tr>

<?php
$result = $pdo->query("SELECT id, name, salary FROM employees");
while (list($id, $name, $salary) = $result->fetch(PDO::FETCH_NUM)) {
    echo " <tr>\n" .
          "  <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
          "  <td>$salary</td>\n" .
          " </tr>\n";
}

?>

</table>

المثال 3: استخدام دالة list()‎‎‎‎ متداخلة

<?php

list($a, list($b, $c)) = array(1, array(2, 3));

var_dump($a, $b, $c);

?>

int(1)
int(2)
int(3)

المثال 4: استخدام list()‎‎‎‎ مع فهارس المصفوفة

<?php

$info = array('coffee', 'brown', 'caffeine');

list($a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>

سوف تكون مُخرجات المثال أعلاه كالتالي (لاحظ ترتيب العناصر مقارنة بترتيب كتابته في البناء اللغوي للدالةlist()‎‎‎‎) كما يلي في PHP 7:

array(3) {
  [0]=>
  string(6) "coffee"
  [1]=>
  string(5) "brown"
  [2]=>
  string(8) "caffeine"
}

أما في PHP 5، فستكون المخرجات كالتالي:

array(3) {
  [2]=>
  string(8) "caffeine"
  [1]=>
  string(5) "brown"
  [0]=>
  string(6) "coffee"
}

المثال 5: الدالة list()‎‎‎‎ وترتيب تعريفات الفهرس الترتيب الذي تُعرّف به فهارس المصفوفة التي تُستهلك بواسطة الدالة list()‎‎‎ ليس مهمًا.

<?php
$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
$foo[1] = 'd';
list($x, $y, $z) = $foo;
var_dump($foo, $x, $y, $z);
?>

سوف تكون مُخرجات المثال أعلاه كالتالي (لاحظ ترتيب العناصر مقارنة بترتيب كتابته في البناء اللغوي للدالة list()‎‎‎‎):

array(4) {
  [2]=>
  string(1) "a"
  ["foo"]=>
  string(1) "b"
  [0]=>
  string(1) "c"
  [1]=>
  string(1) "d"
}
string(1) "c"
string(1) "d"
string(1) "a"

انظر أيضًا

• الدالة each()‎‎‎: إعادة كل من المفتاح والقيمة المقابلة الحاليين من المصفوفة وتحريك مؤشرها للأمام.
• الدالة array()‎‎: إنشاء مصفوفة جديدة.
• الدالة extract()‎‎‎: استخلاص المتغيرات من مصفوفة ما وإدخالها في جدول الرموز الحالي.

مصادر

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