الدالة pathinfo() في PHP
(PHP 4 >= 4.0.3, PHP 5, PHP 7)
تعيد الدالة pathinfo() معلومات عن مسار الملف.
الوصف
mixed pathinfo ( string $path [, int $options = PATHINFO_DIRNAME | PATHINFO_BASENAME | PATHINFO_EXTENSION | PATHINFO_FILENAME ] )
تعيد هذه الدالة معلومات عن المسار path المعطى، وتكون تلك المعلومات إمَّا مصفوفة من القيم أو سلسلة نصيَّة فقط بناءً على قيمة المعامل options.
ملاحظة: اقرأ للمزيد من التفاصيل حول استرجاع معلومات المسار الحالي قسم المتغيرات المُعرَّفة مسبقًا.
تحذير: تأخذ الدالة pathinfo() قيمة المحليَّة (locale) بالحسبان، لذا يجب ضبط القيمة المناسبة للمحليَّة باستعمال الدالة setlocale() إن احتوى المسار على محارف متعدِّدة البايتات لتتمكن الدالة من تحليله بطريقة صحيحة.
المعاملات
path
المسار المراد تحليله.
options
يحدِّد هذا المعامل المعلومات المُعادة وذلك باستعمال الثوابت التالية:
PATHINFO_DIRNAME: يُعاد اسم المجلَّد.PATHINFO_BASENAME: يُعاد اسم الملف الأساسي.PATHINFO_EXTENSION: يُعاد امتداد الملف.PATHINFO_FILENAME: يُعاد اسم الملف.
إن لم تعطَ قيمة هذا المعامل، فستُعاد كلُّ المعلومات المتوافرة.
القيم المعادة
إن لم يمرَّر المعامل options، فستُعاد مصفوفة تحتوي على المعلومات التالية: اسم المجلد، واسم الملف أو المجلَّد الأساسي، والامتدادات (إن وجدت)، واسم الملف.
ملاحظة: إن كان للملف ذو المسار path أكثر من امتداد واحد، فسيعيد الثابت PATHINFO_EXTENSION الامتداد الأخير فقط؛ أمَّا الثابت PATHINFO_FILENAME سيزيل ذلك الامتداد الأخير فقط ثمَّ يعيد اسم الملف مع الامتدادات المتبقيَّة. (انظر إلى المثال 1 في قسم الأمثلة).
ملاحظة: إن لم يكن للمسار path أيُّ امتداد، فلن تُعاد أيَّة قيمة للامتداد. (انظر المثال 2 في قسم الأمثلة).
ملاحظة: إن بَدأ الاسم الأساسي للمسار path بنقطة، فستُفسَّر المحارف التي بعدها على أنَّها امتداد وسيكون حينئذٍ اسم الملف فارغًا. (انظر المثال 3 في قسم الأمثلة).
إن مُرِّر المعامل options، فستُعاد سلسلة نصيَّة تحتوي على المعلومات المحدَّدة بهذا الخيار.
سجل التغييرات
| الإصدار | الوصف |
|---|---|
| 5.2.0 | إضافة الثابت PATHINFO_FILENAME.
|
أمثلة
المثال 1: استعمال الدالة pathinfo()
<?php
$path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');
echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n"; // PHP 5.2.0 منذ إصدار
?>
سيُظهر المثال السابق النتيجة التالية:
/www/htdocs/inc
lib.inc.php
php
lib.inc
المثال 2: إظهار الفارق بين عدم وجود امتداد مطلقًا وبين وجود امتداد ذي قيمة فارغة
<?php
$path_parts = pathinfo('/path/emptyextension.');
var_dump($path_parts['extension']);
$path_parts = pathinfo('/path/noextension');
var_dump($path_parts['extension']);
?>
سيُظهر المثال نتيجة شبيهة بالتالي:
string(0) ""
Notice: Undefined index: extension in test.php on line 6
NULL
المثال 3: استعمال ملف ذي اسم يبتدئ بنقطة
<?php
print_r(pathinfo('/some/path/.test'));
?>
سيُظهر المثال نتيجة شبيهة بالتالي:
Array
(
[dirname] => /some/path
[basename] => .test
[extension] => test
[filename] =>
)
انظر أيضًا
- الدالة
dirname(): تعيد مسار المجلَّد الأب. - الدالة
basename(): تعيد اسم الملف أو المجلَّد الأساسي. - الدالة
parse_url(): تحلِّل العنوان URL الممرر إليها ثمَّ تعيد عناصره. - الدالة realpath(): تعيد المسار المجرَّد الأساسي للمسار المُمرَّر إليها.