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

(PHP 4, PHP 5, PHP 7)

تعيد الدالة scandir()‎ أسماء جميع الملفات والمجلَّدات الموجودة في مجلَّد محدَّد.

الوصف

array scandir ( string $directory [, int $sorting_order = SCANDIR_SORT_ASCENDING [, resource $context ]] )

تعيد هذه الدالة مصفوفةً تحتوي على أسماء الملفات والمجلَّدات الموجودة في المجلَّد directory المعطى.

المعاملات

directory

المجلَّد المراد مسح جميع محتوياته وإعادتها.

sorting_order

طريقة ترتيب الناتج الافتراضيَّة هي وفقًا للحروف الهجائية بشكل تصاعدي (أي عندما لا تمرَّر قيمة للمعامل). إن كانت قيمة هذا المعامل هي SCANDIR_SORT_DESCENDING، فستكون طريقة الترتيب وفقًا للحروف الهجائية ولكن تنازليًّا. أمَّا إن كان قيمة هذا المعامل هي SCANDIR_SORT_NONE، فسيُعاد الناتج دون ترتيب.

context

راجع قسم المجرى (stream) للمزيد من الشرح عن المعامل context.

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

تُعاد مصفوفة تحتوي على أسماء الملفات والمجلَّدات الموجودة في المجلَّد directory عند نجاح العمليَّة، أو القيمة FALSE عند فشلها. إن لم يكن المعامل directory مجلدًا، فستُعاد القيمة FALSE المنطقيَّة وسيُصدر خطأ من المستوى E_WARNING.

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

الإصدار	الوصف
5.4.0	إضافة الثابت sorting_order. كانت أيُّ قيمة غير صفريَّة تؤدِّي إلى ترتيب النتائج تنازليًّا في الإصدارات السابقة. يمكن استعمال القيمة 0 في جميع إصدارات PHP لترتيب النتائج تصاعديًّا، والقيمة 1 لترتيبه تنازليًّا. لم يكن هنالك خيار يؤدِّي السلوك ذاته الذي يؤديه الخيار SCANDIR_SORT_NONE قبل الإصدار PHP 5.4.0.

أمثلة

المثال 1: استعمال الدالة scandir()‎

<?php
$dir    = '/tmp';
$files1 = scandir($dir);
$files2 = scandir($dir, 1);

print_r($files1);
print_r($files2);
?>

سيُظهر المثال السابق نتيجة شبيهة بالتالي:

Array
(
    [0] => .
    [1] => ..
    [2] => bar.php
    [3] => foo.txt
    [4] => somedir
)
Array
(
    [0] => somedir
    [1] => foo.txt
    [2] => bar.php
    [3] => ..
    [4] => .
)

ملاحظات

فائدة: يمكن استعمال عنوان URL مع المعامل directory، أي عوضًا عن اسم المجلَّد، شرط أن يُفعَّل الضبط "fopen wrapper". راجع صفحة الدالة fopen()‎ للمزيد من التفاصيل حول كيفيَّة تحديد اسم المجلَّد.

انظر أيضًا

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

مصادر

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