الدالة file_get_contents() في PHP: قراءة ملف إلى نص

تقرأ file_get_contents('notes.txt') الملف كاملًا وتعيده نصًا واحدًا. وإذا تعذرت قراءة الملف تعيد false. وللكتابة، استخدم file_put_contents('notes.txt', $text)، التي تنشئ الملف أو تستبدل ما كان فيه.

<?php
file_put_contents('notes.txt', "Buy milk\nCall Ada\nWrite docs\n");

$text = file_get_contents('notes.txt');

echo $text;
echo strlen($text), " bytes\n";
echo substr_count($text, "\n"), " lines\n";

المخرجات:

Buy milk
Call Ada
Write docs
29 bytes
3 lines

تكتب الكتلة notes.txt أولًا ثم تقرؤه، فيكون لديها ملف تعمل عليه. والمسار مثل 'notes.txt' نسبي إلى مجلد العمل الحالي؛ وفي تطبيق ويب، ابنِ المسار من مجلد السكربت نفسه بـ __DIR__ . '/notes.txt'.

الكتابة والإضافة بـ file_put_contents()

تعيد file_put_contents() عدد البايتات المكتوبة، أو false عند الفشل. وافتراضيًا تستبدل الملف. ويضيف العلم FILE_APPEND إلى النهاية بدلًا من ذلك، وهكذا تعمل السجلات البسيطة، ويمنع LOCK_EX طلبين من الكتابة في اللحظة نفسها:

<?php
$bytes = file_put_contents('log.txt', "started\n");
echo "Wrote $bytes bytes\n";

file_put_contents('log.txt', "step 1 done\n", FILE_APPEND | LOCK_EX);
file_put_contents('log.txt', "step 2 done\n", FILE_APPEND | LOCK_EX);
echo file_get_contents('log.txt'), "\n";

file_put_contents('log.txt', "replaced\n");   // no flag: the old content is gone
echo file_get_contents('log.txt'), "\n";

// An array is written with its elements joined, with nothing between them
file_put_contents('list.txt', ['a', 'b', 'c']);
echo file_get_contents('list.txt'), "\n";
echo file_put_contents('list.txt', implode("\n", ['a', 'b', 'c'])), " bytes\n";

المخرجات:

Wrote 8 bytes
started
step 1 done
step 2 done

replaced

abc
5 bytes

لتخزين مصفوفة واستعادتها مصفوفةً، اكتبها JSON بـ json_encode() واقرأها بـ json_decode().

قراءة ملف سطرًا سطرًا بـ file()

تقرأ file() ملفًا إلى مصفوفة فيها سطر واحد لكل عنصر. يحتفظ كل سطر بمحرف السطر الجديد في نهايته ما لم تمرر FILE_IGNORE_NEW_LINES، ويُسقط FILE_SKIP_EMPTY_LINES الأسطر الفارغة (ولا يعمل إلا مع FILE_IGNORE_NEW_LINES):

<?php
file_put_contents('todo.txt', "Buy milk\nCall Ada\n\nWrite docs\n");

$lines = file('todo.txt');
var_dump($lines[0]);   // the newline is still there

$lines = file('todo.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
foreach ($lines as $i => $line) {
    echo $i + 1, ". $line\n";
}

echo count($lines), " tasks\n";

المخرجات:

string(9) "Buy milk
"
1. Buy milk
2. Call Ada
3. Write docs
3 tasks

تحمّل file() وfile_get_contents() الملف كاملًا في الذاكرة. وهذا مقبول لملفات الإعدادات والسجلات التي حجمها بضعة ميغابايتات. أما لملف من مئات الميغابايتات، فاقرأه سطرًا في كل مرة بـ fopen() وfgets() بدلًا من ذلك.

التحقق من وجود الملف قبل قراءته

عندما يكون الملف مفقودًا، تعيد file_get_contents() القيمة false وتطبع PHP تحذيرًا:

Warning: file_get_contents(missing.txt): Failed to open stream: No such file or directory in /home/index.php on line 2

افحص أولًا بـ is_file() (ملف موجود وليس مجلدًا) أو file_exists() (ملف أو مجلد)، وقارن النتيجة دائمًا بـ === false، لأن الملف الفارغ يعيد ""، وهو خاطئ منطقيًا أيضًا:

<?php
file_put_contents('empty.txt', '');

foreach (['empty.txt', 'missing.txt', '.'] as $path) {
    echo str_pad($path, 12);
    echo file_exists($path) ? 'exists ' : 'missing ';
    echo is_file($path) ? 'file ' : '';
    echo is_dir($path) ? 'directory ' : '';
    echo "\n";
}

$path = 'missing.txt';
if (!is_file($path) || !is_readable($path)) {
    echo "Cannot read $path, using defaults\n";
} else {
    $text = file_get_contents($path);
}

$text = file_get_contents('empty.txt');
var_dump($text === false, $text == false);   // not a failure, just empty
echo filesize('empty.txt'), " bytes\n";

المخرجات:

empty.txt   exists file 
missing.txt missing 
.           exists directory 
Cannot read missing.txt, using defaults
bool(false)
bool(true)
0 bytes

لا تُخفِ التحذير بـ @file_get_contents(). الفحص أولًا، أو معالجة false، يُبقي الخطأ مرئيًا عندما يحدث خلل آخر.

قراءة جزء من ملف

الوسيطان الرابع والخامس هما إزاحة البايت التي يُبدأ منها وعدد البايتات المقروءة. والإزاحة السالبة تُعدّ من نهاية الملف. وتتيح لك الوسائط المسماة تخطي الوسيطين اللذين بينهما:

<?php
file_put_contents('data.txt', "HEADER\nline 2\nline 3\nlast line\n");

echo file_get_contents('data.txt', false, null, 0, 6), "\n";   // first 6 bytes
echo file_get_contents('data.txt', offset: 7, length: 6), "\n";
echo file_get_contents('data.txt', offset: -10);                 // last 10 bytes

المخرجات:

HEADER
line 2
last line

تعدّ الإزاحات البايتات لا المحارف. وفي UTF-8 يكون المحرف الياباني 3 بايتات، فتقطعه إزاحة في منتصفه إلى نصفين. وللعمل مع المحارف، اقرأ النص كاملًا واستخدم mb_substr().

عرض ملف نصي على صفحة ويب

محتويات الملف نص، والنص المطبوع في HTML يجب تهريبه، وإلا أصبح < في الملف وسمًا. تهرّبه htmlspecialchars() وتحوّل nl2br() الأسطر الجديدة إلى وسوم <br>. شغّله وانظر إلى تبويب Page:

<?php
file_put_contents('changelog.txt', <<<TXT
v1.2: Fixed <title> encoding
v1.1: Added "export" & "import"
v1.0: First release
TXT);

$text = file_get_contents('changelog.txt');
?>
<h3>Changelog</h3>
<p style="font-family: monospace"><?= nl2br(htmlspecialchars($text)) ?></p>
<p><?= count(file('changelog.txt')) ?> entries, <?= filesize('changelog.txt') ?> bytes</p>

احذف htmlspecialchars() وشغّله مرة أخرى: تنتهي الصفحة الآن عند "v1.2: Fixed"، لأن المتصفح يقرأ <title> وسمًا حقيقيًا ويبتلع كل ما بعده عنوانًا للصفحة. وتشرح صفحة htmlspecialchars() لماذا يهم ذلك لكل ما يستطيع المستخدم كتابته.

قراءة رابط بـ file_get_contents()

مع تفعيل allow_url_fopen (الافتراضي في php.ini)، تقرأ file_get_contents() الروابط أيضًا وتعيد جسم الاستجابة. ويضيف سياق التدفق طريقة الطلب والترويسات والجسم والمهلة:

<?php
$html = file_get_contents('https://example.com/');

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['name' => 'Ada']),
        'timeout' => 5,
        'ignore_errors' => true,   // return the body of 4xx/5xx responses too
    ],
]);

$response = file_get_contents('https://api.example.com/users', false, $context);
if ($response === false) {
    // DNS failure, timeout, or a refused connection
}

لإعادة المحاولة، والتحويلات المحدودة، ورموز الأخطاء الواضحة، تكون cURL أو مكتبة عميل HTTP مثل Guzzle الأداة الأفضل.

file_get_contents مقابل file() مقابل fopen()

تفتح الدوال ذات الاستدعاء الواحد الملف، وتقرأ أو تكتب، وتغلقه نيابة عنك، لذا فهي الخيار الافتراضي الصحيح. واستخدم fopen() عندما يكون الملف أكبر من أن يُحمل في الذاكرة أو تحتاج إلى إبقائه مفتوحًا بين العمليات.