الدالة file_put_contents() في PHP
(PHP 5, PHP 7)
تكتب الدالة file_put_contents() سلسلة نصيَّة على ملف.
الوصف
int file_put_contents ( string $filename , mixed $data [, int $flags = 0 [, resource $context ]] )
عمل هذه الدالة مشابه تمامًا لعمليَّة استدعاء الدالة fopen() والدالة fwrite() والدالة fclose() على التوالي وذلك لكتابة بيانات على ملف.
إن لم يكن الملف filename موجودًا، فسيُنشأ ويضاف إليه البيانات. إن كان موجودًا، فسيُستبدل إلا إذا كانت إحدى قيم المعامل flags هي الراية FILE_APPEND.
المعاملات
filename
مسار الملف المراد كتابة البيانات عليه.
data
البيانات التي ستُكتب على الملف، ويمكن أن يكون هذا المعامل سلسلة نصيَّة أو مصفوفة أو مورد لمجرى ما.
إن كان المعامل data موردًا لمجرى، فسيُنسخ المخزن المتبقي لذلك المجرى إلى الملف المحدَّد. هذا شبيه باستعمال الدالة stream_copy_to_stream().
يمكن أن يكون المعامل data مصفوفة أحادية البعد، وهذا مطابق للحالة file_put_contents($filename, implode('', $array)).
flags
يمكن أن تكون قيمة هذا المعامل أحد الرايات الموضَّحة في الجدول التالي أو خليطًا منها إذ تُجمع أكثر من راية باستعمال المعامل OR الثنائي (|).
| الراية | الوصف |
|---|---|
FILE_USE_INCLUDE_PATH
|
البحث على الملف filename في المجلَّد المُضمَّن. راجع صفحة include_path للمزيد من المعلومات.
|
FILE_APPEND
|
إن كان الملف filename موجودًا، فستُضاف البيانات إليه عوضًا عن استبداله.
|
LOCK_EX
|
قفل الملف بقفلٍ خاصٍّ (exclusive lock) عند إجراء عمليَّة الكتابة. بعبارة أخرى، يحدث استدعاء الدالة flock() بين استدعاء الدالة fopen() واستدعاء الدالة fwrite(). لا يماثل ذلك استدعاء الدالة fopen() مع الوضع "x".
|
context
مورد محتوى صحيح أُنشئ باستعمال الدالة stream_context_create().
القيم المعادة
تُعاد عدد البياتات التي كُتبت على الملف، أو القيمة FALSE عند فشل العمليَّة.
تحذير: تعيد هذه الدالة أحيانًا القيمة المنطقيَّة FALSE وتعيد أحيانًا أخرى قيمة غير منطقيَّة ولكنَّها تعادل القيمة FALSE، لذا استعمل المعامل === للتحقُّق من القيمة المُعادة. راجع قسم القيم المنطقيَّة (booleans) للاطلاع على المزيد من المعلومات.
أمثلة
المثال 1: أبسط استعمال للدالة file_put_contents()
<?php
$file = 'people.txt';
// فتح الملف للحصول على محتواه
$current = file_get_contents($file);
// إضافة شخص جديد للمحتوى
$current .= "John Smith\n";
// إعادة كتابة المحتوى على الملف
file_put_contents($file, $current);
?>
المثال 2: استعمال الدالة file_put_contents() مع المعامل flags
<?php
$file = 'people.txt';
// الشخص الجديد المراد إضافته إلى الملف
$person = "John Smith\n";
//:كتابة المحتوى إلى الملف باستعمال
//لإضافة المحتوى إلى نهاية الملف FILE_APPEND الراية
//لمنع أي أحد من الكتابة على الملف في الوقت ذاته LOCK_EX والراية
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>
سجل التغييرات
| الإصدار | الوصف |
|---|---|
| 5.1.0 | إضافة دعم للراية LOCK_EX بالإضافة إلى امكانيَّة تمرير مورد مجرى للمعامل data.
|
ملاحظات
هذه الدالة آمنة ثنائيًّا (binary safe).
فائدة: يمكن استعمال عنوان URL مع المعامل filename، أي عوضًا عن اسم الملف، شرط أن يُفعَّل الضبط "fopen wrapper". راجع صفحة الدالة fopen() للمزيد من التفاصيل حول كيفيَّة تحديد الملف.
انظر أيضًا
- الدالة
fopen(): تفتح ملفًا أو عنوان URL. - الدالة
fwrite(): تكتب بطريقة آمنة ثنائيًّا على ملف. - الدالة
file_get_contents(): تقرأ الملف ثمَّ تضع كلَّ محتوياته في سلسلة نصيَّة. - الدالة
stream_context_create(): تنشئ محتوى مجرى.