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

(PHP 4, PHP 5, PHP 7)

تكتب الدالة fwrite()‎ على ملف معيَّن بطريقة آمنة ثنائيًّا.

الوصف

int fwrite ( resource $handle , string $string [, int $length ] )

تكتب هذه الدالة محتوى السلسلة النصيَّة string على الملف الذي يشير إليه المورد handle.

المعاملات

handle

مؤشِّر (pointer) يشير إلى ملف. يجب أن يكون سليمًا، ويشير إلى ملف فُتح بطريقة صحيحة باستعمال الدالة fopen()‎.

string

السلسلة النصيَّة المراد كتابتها على الملف.

length

إن أُعطيت قيمة هذا المعامل، فستتوقف عمليَّة القراءة عند كتابة عدد محدَّد من البايتات التي تمثلها تلك القيمة أو عند كتابة كامل محتوى السلسلة النصيَّة أيهما يتحقَّق أولًا.

الجدير بالملاحظة أنَّه عندما تُعطى قيمة المعامل length سيُتجاهل الضبط magic_quotes_runtime ولن تُزال أي خطوط مائلة (slashes) من السلسلة النصيَّة string.

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

يُعاد عدد البايتات التي كُتبت على الملف. إن حصل أي خطأ، فستُعاد القيمة FALSE.

ملاحظات

• قد تنتهي عمليَّة الكتابة على مجرى شبكة قبل الإنتهاء من كتابة كامل السلسلة النصيَّة، لذا تحقَّق في هذه الحالة من عدد البايتات المكتوبة التي تعيدها الدالة fwrite()‎.

	<?php
function fwrite_stream($fp, $string) {
 	   for ($written = 0; $written < strlen($string); $written += $fwrite) {
 	       $fwrite = fwrite($fp, substr($string, $written));
  	      if ($fwrite === false) {
 	           return $written;
 	       }
    }
    return $written;
}
?>

• يجب عند استعمال أنظمة تفرِّق بين المحتوى النصي والثنائي مثل نظام ويندوز أن يُفتح الملف بإضافة الراية 'b' إلى قيمة المعامل mode في الدالة fopen()‎.
• إن فتح الملف في الوضع 'a' أو 'a+‎' (إضافة البيانات إلى نهاية الملف) باستعمال الدالة fopen()‎، فستكتب جميع البيانات إلى الملف دون مقاطعة (إلا إذا تجاوز حجم السلسلة النصيَّة string حجم كتلة (block) نظام الملفات، على بعض المنصات، وطالما كان الملف موجودًا على نظام الملفات المحلي). بعبارة أخرى، لا يوجد حاجة لاستدعاء الدالة flock()‎ -لحماية الملف وقفله- قبل استدعاء الدالة fwrite()‎.
• إن كُتبت البيانات على الملف ذاته باستدعاء هذه الدالة مرتين أو أكثر، فستضاف البيانات الجديدة إلى نهاية محتوى ذلك الملف.

<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);
	
//هو 123 وليس 23 'data.txt' أصبح محتوى الملف
?>

أمثلة

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

<?php
$filename = 'test.txt';
$somecontent = "Add this to the file\n";

// لنتأكد أولًا أن الملف موجود وقابل للكتابة
if (is_writable($filename)) {

    //(’a’  في وضع الإضافة (الوضع $filename سنفتح في مثالنا الملف
    // وبذلك سيتوضع مؤشِّر الملف في نهاية الملف حيث سيضاف
    // هنالك عند كتابته على الملف $somecontent المحتوى
    if (!$handle = fopen($filename, 'a')) {
         echo "Cannot open file ($filename)";
         exit;
    }

    // إلى الملف المفتوح $somecontent سنضيف الآن المحتوى
    if (fwrite($handle, $somecontent) === FALSE) {
        echo "Cannot write to file ($filename)";
        exit;
    }

    echo "Success, wrote ($somecontent) to file ($filename)";

    fclose($handle);

} else {
    echo "The file $filename is not writable";
}
?>

انظر أيضًا

• الدالة fopen()‎: تفتح ملفًا أو عنوان URL.
• الدالة popen()‎: تفتح عمليَّة وتشير إليها بمؤشِّر شبيه بمؤشِّر ملف.
• الدالة fsockopen()‎: تفتح اتصالًا بالإنترنت أو بمقبس نطاق يونكس (Unix domain socket).
• الدالة fread()‎: تقرأ من الملف بطريقة آمنة ثنائيًّا.
• الدالة file_get_contents()‎: تقرأ الملف ثمَّ تضع كلَّ محتوياته في سلسلة نصيَّة.
• الدالة unpack()‎: تحزِّم البيانات في سلسلة نصيَّة بالنظام الثنائي.

مصادر

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