fopen() في PHP: فتح الملفات وقراءتها وكتابتها مع شرح الأوضاع

تفتح fopen('data.txt', 'r') ملفًا وتعيد مقبضًا، مورد تدفق تأخذه دوال الملفات الأخرى وسيطًا أول. اقرأ بـ fgets() (سطر واحد) أو fread() (عدد من البايتات)، واكتب بـ fwrite()، وأغلق بـ fclose(). والوسيط الثاني هو الوضع: 'r' للقراءة، و'w' للكتابة، و'a' للإضافة.

<?php
$fh = fopen('fruits.txt', 'w');          // create or empty the file
fwrite($fh, "apple\n");
fwrite($fh, "banana\n");
fwrite($fh, "cherry\n");
fclose($fh);

$fh = fopen('fruits.txt', 'r');
if ($fh === false) {
    exit("Cannot open fruits.txt\n");
}

while (($line = fgets($fh)) !== false) {
    echo 'Got: ', rtrim($line), "\n";
}
fclose($fh);

المخرجات:

Got: apple
Got: banana
Got: cherry

تعيد fopen() القيمة false عندما لا تستطيع فتح الملف (غير موجود في الوضع r، أو مجلد مفقود، أو لا صلاحية)، وتطبع PHP تحذيرًا مثل:

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

لذا افحص false قبل استخدام المقبض. ولقراءة ملف صغير كامل أو كتابته في استدعاء واحد، تكون file_get_contents() وfile_put_contents() أقصر؛ أما fopen() فللملفات التي تقرؤها جزءًا جزءًا أو تبقيها مفتوحة.

أوضاع fopen

صفان يفاجئان الناس. يكتب r+ فوق البايتات الموجودة في مكانها، دون إدراج، ويكتب a+ دائمًا في النهاية، حتى بعد أن تحرّك المؤشر بـ fseek() (تحريكه لا يؤثر إلا في القراءة):

<?php
file_put_contents('letters.txt', "abc\n");

$fh = fopen('letters.txt', 'r+');
fwrite($fh, 'X');                  // overwrites the "a"
fclose($fh);
echo file_get_contents('letters.txt');

$fh = fopen('letters.txt', 'a+');
fseek($fh, 0);                     // back to the start...
fwrite($fh, "end\n");              // ...but the write still goes to the end
rewind($fh);
echo fgets($fh);                   // reads do start at the beginning
fclose($fh);
echo file_get_contents('letters.txt');

المخرجات:

Xbc
Xbc
Xbc
end

على Windows قد ترى 'rb' أو 'wb': العلم b يعني ثنائي ويمنع Windows من تحويل نهايات الأسطر. ولا يفعل شيئًا على Linux وmacOS، لذا فإضافته غير ضارة وقابلة للنقل.

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

تعيد fgets() السطر التالي متضمنًا \n الخاص به، وfalse عند نهاية الملف. ولأن سطرًا واحدًا فقط يكون في الذاكرة في كل مرة، تتعامل هذه الحلقة مع ملف سجل بأي حجم، ويمكنك التوقف مبكرًا بـ break:

<?php
file_put_contents('app.log', <<<LOG
2026-03-14 09:00:01 INFO  server started
2026-03-14 09:00:05 ERROR database timeout
2026-03-14 09:01:12 INFO  request /home
2026-03-14 09:02:40 ERROR disk full
2026-03-14 09:03:00 INFO  request /about
LOG);

$fh = fopen('app.log', 'r');
$number = 0;
$errors = [];

while (($line = fgets($fh)) !== false) {
    $number++;
    if (str_contains($line, 'ERROR')) {
        $errors[] = "line $number: " . trim(substr($line, 26));
    }
}
fclose($fh);

echo count($errors), " errors in $number lines\n";
echo implode("\n", $errors), "\n";

المخرجات:

2 errors in 5 lines
line 2: database timeout
line 4: disk full

قارن بـ false باستخدام !==، لا بـ while ($line = fgets($fh)) البسيطة: السطر الذي لا يحتوي إلا "0" دون سطر جديد (وقد يكون آخر سطر في الملف كذلك) خاطئ منطقيًا وسينهي الحلقة مبكرًا.

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

تكتب fwrite() نصًا عند الموضع الحالي وتعيد عدد البايتات المكتوبة، أو false عند الفشل. وfputs() هي الدالة نفسها باسم آخر. افتح بـ 'a' للإضافة إلى نهاية ملف دون لمس ما فيه:

<?php
$fh = fopen('visits.log', 'a');
foreach (['/home', '/about', '/contact'] as $page) {
    $bytes = fwrite($fh, "visit $page" . PHP_EOL);
    echo "wrote $bytes bytes\n";
}
fclose($fh);

$fh = fopen('visits.log', 'a');      // open again: the old lines stay
fwrite($fh, 'visit /home' . PHP_EOL);
fclose($fh);

echo file_get_contents('visits.log');

المخرجات:

wrote 12 bytes
wrote 13 bytes
wrote 15 bytes
visit /home
visit /about
visit /contact
visit /home

PHP_EOL هو نهاية السطر للنظام الذي تعمل عليه PHP (\n على Linux وmacOS، و\r\n على Windows). وللملفات التي تقرؤها برامج أخرى، اختر واحدة صراحة، عادة "\n".

قراءة ملفات CSV وكتابتها بـ fgetcsv() وfputcsv()

تكتب fputcsv() مصفوفة صفًا واحدًا في CSV وتضع علامات تنصيص حول الحقول التي تحتوي فواصل أو علامات تنصيص أو أسطرًا جديدة. وتقرأ fgetcsv() صفًا واحدًا مصفوفةً. مرّر الفاصل ومحرف الإحاطة ومحرف هروب فارغًا صراحة: هذا يعطي CSV قياسيًا، وتطبع PHP 8.4 إشعار إهمال عندما يُحذف وسيط الهروب.

<?php
$rows = [
    ['name', 'city', 'note'],
    ['Ada', 'London', 'likes "math", a lot'],
    ['Linus', 'Helsinki', 'kernel'],
];

$fh = fopen('people.csv', 'w');
foreach ($rows as $row) {
    fputcsv($fh, $row, ',', '"', '');
}
fclose($fh);
echo file_get_contents('people.csv'), "\n";

// Read it back, using the first row as keys
$fh = fopen('people.csv', 'r');
$header = fgetcsv($fh, null, ',', '"', '');
while (($fields = fgetcsv($fh, null, ',', '"', '')) !== false) {
    $person = array_combine($header, $fields);
    echo "{$person['name']} lives in {$person['city']}: {$person['note']}\n";
}
fclose($fh);

المخرجات:

name,city,note
Ada,London,"likes ""math"", a lot"
Linus,Helsinki,kernel

Ada lives in London: likes "math", a lot
Linus lives in Helsinki: kernel

تقسيم الأسطر بـ explode(',', $line) ينكسر حالما يحتوي حقل فاصلة؛ وتعالج fgetcsv() علامات التنصيص نيابة عنك. ولملف مفصول بفواصل منقوطة (شائع في ملفات Excel المصدّرة في أوروبا)، مرّر ';' فاصلًا.

التنقل في ملف بـ fseek() وftell() وrewind()

للملف المفتوح موضع. تبدأ القراءات والكتابات منه وتحرّكه إلى الأمام. تخبرك ftell() بمكانه، وتنقله fseek() إلى إزاحة بايت، وتعيده rewind() إلى البداية. ومع w+ يمكنك كتابة ملف وقراءته عبر المقبض نفسه:

<?php
$fh = fopen('message.txt', 'w+');
fwrite($fh, 'hello world');
echo ftell($fh), "\n";             // after the last byte written

fseek($fh, 6);
echo fread($fh, 5), "\n";          // 5 bytes from offset 6

rewind($fh);
echo stream_get_contents($fh), "\n";  // everything from the position to the end
fclose($fh);

المخرجات:

11
world
hello world

قفل ملف بـ flock()

طلبان يقرآن عدادًا، ويضيفان واحدًا، ويكتبانه في الوقت نفسه قد يقرآ كلاهما 41 ويكتبا كلاهما 42. تجعل flock() مع LOCK_EX الطلب الثاني ينتظر حتى يحرر الأول القفل. والوضع c+ هو الصحيح هنا: ينشئ الملف عند الحاجة، وعلى عكس w+، لا يُفرغه قبل أن تمسك القفل.

<?php
function increment(string $path): int
{
    $fh = fopen($path, 'c+');
    flock($fh, LOCK_EX);               // wait for exclusive access

    $count = (int) stream_get_contents($fh);
    $count++;

    ftruncate($fh, 0);                 // empty the file
    rewind($fh);
    fwrite($fh, (string) $count);
    fflush($fh);

    flock($fh, LOCK_UN);
    fclose($fh);
    return $count;
}

for ($i = 0; $i < 3; $i++) {
    echo 'Visitor number ', increment('counter.txt'), "\n";
}

المخرجات:

Visitor number 1
Visitor number 2
Visitor number 3

الأقفال استشارية: لا توقف إلا الشيفرة الأخرى التي تستدعي flock() أيضًا. ولإضافة سطر واحد، تفعل file_put_contents($path, $line, FILE_APPEND | LOCK_EX) الشيء نفسه في استدعاء واحد.

خطأ شائع: while (!feof($fh))

تمر دروس قديمة كثيرة بحلقة على feof(). لا تعيد true إلا بعد أن تكون قراءة قد اصطدمت بالنهاية فعلًا، فتعمل الحلقة مرة أكثر من عدد الأسطر وتعيد fgets() الأخيرة false:

<?php
file_put_contents('abc.txt', "a\nb\nc\n");

$fh = fopen('abc.txt', 'r');
$rounds = 0;
while (!feof($fh)) {
    $line = fgets($fh);
    $rounds++;
    var_dump($line);
}
fclose($fh);
echo "$rounds rounds for 3 lines\n";

المخرجات:

string(2) "a
"
string(2) "b
"
string(2) "c
"
bool(false)
4 rounds for 3 lines

تصبح قيمة false الزائدة تلك صفًا فارغًا في تقرير أو عنصرًا فارغًا في مصفوفة. اجعل الحلقة على القراءة نفسها، while (($line = fgets($fh)) !== false)، كما تفعل كل الأمثلة الأخرى في هذه الصفحة.