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

(PHP 4, PHP 5, PHP 7)

تعيد الدالة stat()‎ معلومات عن ملف محدَّد.

الوصف

array stat ( string $filename )

تجمع هذه الدالة بعض المعلومات الإحصائيَّة عن الملف filename. إن كان الملف filename وصلة رمزيَّة، فستعاد معلومات إحصائيَّة عن الملف ذاته الذي تشير إليه الوصلة وليست عن الوصلة الرمزيَّة تلك.

الدالة lstat()‎ مطابقة تمامًا للدالة stat()‎ باستثناء أنَّها تعيد معلومات إحصائيَّة عن الوصلات الرمزيَّة أيضًا.

المعاملات

filename

مسار الملف المراد جلب معلومات عنه.

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

يوضِّح الجدول التالي تنسيق المصفوفة التي ستعيدها الدالة stat()‎ والدالة fstat()‎:

الرقم	الارتباط	الوصف
0	dev	رقم الجهاز.
1	ino	رقم مؤشِّر الفهرسة (inode).*
2	mode	وضع حماية مؤشِّر الفهرسة.
3	nlink	عدد الوصلات.
4	uid	معرِّف المستخدم المالك.*
5	gid	معرِّف المجموعة المالكة.*
6	rdev	نوع الجهاز إن كان مؤشِّر الفرسة جهازًا.
7	size	الحجم بالبايت.
8	atime	وقت آخر وصول (يكون على شكل بصمة وقت يونكس [Unix timestamp]).
9	mtime	وقت آخر تعديل (يكون على شكل بصمة وقت يونكس [Unix timestamp]).
10	ctime	وقت آخر تعديل جرى على مؤشِّر الفهرسة (يكون على شكل بصمة وقت يونكس [Unix timestamp]).
11	blksize	حجم كتلة نظام الملفات.**
12	blocks	عدد الكتل المحجوزة من أصل 512 بايت.**

* ستكون قيمتها على ويندوز 0 دومًا.

** ستُعاد قيمة صحيحة على الأنظمة التي تدعم النوع st_blksize؛ أمَّا الأنظمة التي لاتدعمها (مثل ويندوز)، فستُعاد القيمة ‎-1.

ستعيد الدالة stat()‎ القيمة FALSE حال وجود خطأ.

ملاحظة: لمَّا كان نوع الأعداد الصحيحة في PHP هو ذات إشارة (signed) وأغلب المنصات تستعمل الأعداد الصحيحة بطول 32 بت، فقد تعيد بعض دوال نظام الملفات نتائج مخالفة للتوقعات عند استعمالها مع ملفات ذات حجم أكبر من 2 غيغابايت.

الأخطاء والاستثناءات

سيُصدَر تحذير من المستوى E_WARNING عند فشل الدالة.

أمثلة

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

<?php
// جلب معلومات الملف التالي
$stat = stat('C:\php\php.exe');

/*
 * طباعة وقت الوصول للملف، وهذا مشابه تمامًا 
 * fileatime() لاستدعاء الدالة
 */
echo 'Access time: ' . $stat['atime'];

/*
 * طباعة وقت تعديل الملف، وهذا مشابه تمامًا 
 * filemtime() لاستدعاء الدالة
 */
echo 'Modification time: ' . $stat['mtime'];

// طباعة رقم الجهاز
echo 'Device number: ' . $stat['dev'];
?>

المثال 2: استعمال المعلومات التي تعيدها الدالة stat()‎ مع الدالة touch()‎

<?php
// جلب معلومات الملف التالي
$stat = stat('C:\php\php.exe');

// هل سنفشل في جلب المعلومات عند استدعاء الدالة؟
if (!$stat) {
    echo 'stat() call failed...';
} else {
    /*
     * نريد تعديل وقت الوصول ليكون أسبوعًا واحدًا 
     * بدءًا من الوقت الوصول الحالي
     */
    $atime = $stat['atime'] + 604800;

    // ضبط وقت الوصول للملف
    if (!touch('some_file.txt', time(), $atime)) {
        echo 'Failed to touch file...';
    } else {
        echo 'touch() returned success...';
    }
}
?>

ملاحظات

• الجدير بالملاحظة أنَّ دقَّة الوقت قد تختلف من نظام ملفات إلى آخر.
• ستُخزَّن نتيجة هذه الدالة. راجع صفحة الدالة clearstatcache()‎ للمزيد من التفاصيل.

فائدة: يمكن أن تُستعمل هذه الدالة بدءًا من إصدار PHP 5.0.0 مع بعض بروتوكلات الروابط (URL wrappers).

انظر أيضًا

• الدالة lstat()‎: تعيد معلومات عن ملف أو وصلة رمزيَّة.
• الدالة fstat()‎: تعيد معلومات عن ملف باستعمال مؤشِّر ملف مفتوح يشير إليه.
• الدالة filemtime()‎: تجلب آخر وقت جرى فيه تعديل الملف.
• الدالة filegroup()‎: تعيد المجموعة المالكة للملف.

مصادر

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