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

(PHP 4, PHP 5, PHP 7)

تقرأ الدالة readdir()‎ عنصرًا واحدًا من محتويات المجلَّد وتعيده.

الوصف

string readdir ([ resource $dir_handle ] )

تعيد هذه الدالة اسم العنصر التالي الموجود في المجلَّد. تُعاد العناصر بالترتيب الذي خُزَّنت فيه بوساطة نظام الملفات.

المعاملات

dir_handle

مورد مقبض المجلَّد المراد القراءة منه والذي يشير إلى مجلَّد فُتح بطريقة صحيحة باستعمال الدالة opendir()‎. إن لم يعطَ هذا المعامل أي لم يحدَّد المجلَّد، فسيُقرأ من آخر مجلَّد فُتح باستعمال الدالة opendir()‎.

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

يُعاد اسم عنصر واحد موجود في المجلَّد عند نجاح العمليَّة أو القيمة FALSE عند فشلها.

تحذير: تعيد هذه الدالة أحيانًا القيمة المنطقيَّة FALSE وتعيد أحيانًا أخرى قيمة غير منطقيَّة ولكنَّها تعادل القيمة FALSE، لذا استعمل المعامل === للتحقُّق من القيمة المُعادة. راجع قسم القيم المنطقيَّة (booleans) للاطلاع على المزيد من المعلومات.

أمثلة

المثال 1: استعمال الدالة readdir()‎ لطباعة جميع محتويات مجلَّد

انتبه رجاءً إلى الطريقة المستعملة للتأكُّد من القيمة التي تعيدها الدالة readdir()‎ في الشيفرة التالية. سنتحقَّق إن كانت القيمة المعادة مطابقة تمامًا للقيمة FALSE (أي مساويةً لها ومن ذات نوعها؛ راجع قسم عوامل المقارنة للمزيد من المعلومات)؛ سيؤدِّي وجود عنصر في المجلَّد يعادل اسمه القيمة FALSE إلى الخروج من حلقة التكرار (مثل وجود مجلّد اسمه "0").

<?php

if ($handle = opendir('/path/to/files')) {
    echo "Directory handle: $handle\n";
    echo "Entries:\n";

    // هذه هي الطريقة الصحيحة لاستعمال حلقة التكرار في حالتنا هذه 
    while (false !== ($entry = readdir($handle))) {
        echo "$entry\n";
    }

 // هذه هي الطريقة الخطأ لاستعمال حلقة التكرار في حالتنا هذه 
    while ($entry = readdir($handle)) {
        echo "$entry\n";
    }

    closedir($handle);
}
?>

المثال 2: سرد جميع محتويات المجلَّد الحالي باستثناء "." و ".."

<?php
if ($handle = opendir('.')) {
    while (false !== ($entry = readdir($handle))) {
        if ($entry != "." && $entry != "..") {
            echo "$entry\n";
        }
    }
    closedir($handle);
}
?>

انظر أيضًا

• الدالة is_dir()‎: تتحقَّق إن كان المسار المُمرَّر إليها مجلَّدًا.
• الدالة glob()‎: تبحث عن مسارات محدَّدة لملفات أو مجلَّدات تتطابق مع نمط مُعطى.
• الدالة opendir()‎: تفتح مجلَّدًا محدَّدًا.
• الدالة scandir()‎: تعيد جميع الملفات والمجلدات الموجودة بداخل مسار محدَّد.

مصادر

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