الدالة dirname() في PHP
(PHP 4, PHP 5, PHP 7)
تعيد الدالة dirname() مسار المجلَّد الأب لمسار الملف أو المجلَّد الممرَّر إليها.
الوصف
string dirname ( string $path [, int $levels = 1 ] )
تعيد هذه الدالة عند تمرير مسار ملف أو مجلَّد إليها سلسلةً نصيةً تحتوي على مسار المجلَّد الأب ذو المستوى levels بدءًا من المجلَّد الحالي.
ملاحظة: تُجري الدالة dirname() عمليتها على السلسلة النصيَّة المرَّرة إليها بسذاجة ولا تتعرَّف على نظام الملفات الحالي ولا على عناصر المسار مثل "..".
تحذير: تأخذ الدالة dirname() قيمة المحليَّة (locale) بالحسبان، لذا يجب ضبط القيمة المناسبة للمحليَّة باستعمال الدالة setlocale() إن احتوى المسار على محارف متعدِّدة البايتات لتتمكن الدالة من إعادة اسم المجلَّد الصحيح.
المعاملات
path
المسار المراد تحليله.
يُستعمل في ويندوز محرف الخط المائل (/) ومحرف الخط المائل العكسي (\) للفصل بين أسماء المجلَّدات بينما يُستعمل المحرف الأول فقط للغرض ذاته في البيئات الأخرى.
levels
عدد المجلَّدات المراد الرجوع إليها بدءًا من المجلَّد الحالي. يجب أن يكون عددًا صحيحًا أكبر من الصفر.
القيم المعادة
يُعاد مسار المجلَّد الأب ذو المستوى المحدَّد. إن لم يوجد في المسار path أي خط مائل، فستُعاد نقطة ('.') تشير إلى المجلَّد الحالي. خلا ذلك، ستُعاد سلسلة نصيَّة تحتوي على المسار path بعد إزالة بعض الأجزاء أو العناصر الزائدة منه.
سجل التغييرات
| الإصدار | الوصف |
|---|---|
| 7.0.0 | إضافة المعامل الاختياري levels.
|
| 5.0.0 | أصبحت الدالة الآن آمنة ثنائيًّا (binary safe). |
أمثلة
المثال 1: استعمال الدالة dirname()
<?php
echo dirname("/etc/passwd") . PHP_EOL;
echo dirname("/etc/") . PHP_EOL;
echo dirname(".") . PHP_EOL;
echo dirname("C:\\") . PHP_EOL;
echo dirname("/usr/local/lib", 2);
?>
سيُظهر المثال نتيجة شبيهة بالتالي:
/etc
/ (or \ on Windows)
.
C:\
/usr
انظر أيضًا
- الدالة
basename(): تعيد اسم الملف أو المجلَّد الأساسي. - الدالة
pathinfo(): تعيد معلومات عن مسار الملف. - الدالة
realpath(): تعيد المسار المجرَّد الأساسي للمسار المُمرَّر إليها.