fwrite()

Что такое функция fwrite()?

fwrite() — встроенная функция PHP, которая записывает строку в открытый файл. Запись начинается с текущей позиции указателя файла, и после записи указатель смещается на количество записанных байт, поэтому последовательные вызовы дополняют данные, а не перезаписывают их. Это стандартный низкоуровневый способ записи в файлы в PHP; функция также доступна под именем fputs() (обе абсолютно идентичны).

На этой странице рассматриваются синтаксис, необязательный аргумент length, режимы открытия файла, определяющие куда и как записываются данные, возвращаемые значения, обработка ошибок и типичные задачи, для которых применяется fwrite().

Синтаксис

fwrite(resource $stream, string $data, ?int $length = null): int|false

Возвращаемое значение: количество фактически записанных байт или false в случае ошибки. Поскольку на некоторых потоках возможна неполная запись (меньше байт, чем strlen($data)), надёжный код проверяет возвращаемое значение, а не просто предполагает успех.

Аргумент length почти никогда не нужен. fwrite($file, $data) уже записывает всю строку. Передавайте длину только тогда, когда намеренно хотите ограничить вывод первыми N байтами.

Простой пример

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'w');     // open for writing (truncates the file)

if ($file === false) {
    exit("Could not open $filename for writing");
}

$bytes = fwrite($file, "Hello, world!");
fclose($file);

echo "Wrote $bytes bytes."; // Wrote 13 bytes.

Всегда задействованы три шага:

1. Откройте файл с помощью fopen() в режиме, допускающем запись.
2. Вызовите fwrite() один или несколько раз, чтобы передать данные в поток.
3. Закройте файл с помощью fclose(), чтобы сбросить буфер и освободить дескриптор.

"Hello, world!" содержит 13 символов, поэтому fwrite() вернёт 13.

Режимы открытия файла: куда попадают байты

Поведение fwrite() определяется почти исключительно режимом, переданным в fopen(). Это наиболее распространённый источник путаницы, поэтому стоит запомнить:

Если файл постоянно оказывается пустым или теряет вчерашние данные, скорее всего вы открыли его с режимом 'w', когда имели в виду 'a'.

Добавление вместо перезаписи

<?php

$log = fopen('app.log', 'a');           // 'a' keeps existing lines
fwrite($log, "User logged in\n");       // \n adds a newline
fwrite($log, "Order placed\n");
fclose($log);

При каждом запуске этот скрипт добавляет ещё две строки в app.log, не стирая его.

Запись нескольких строк

fwrite() записывает ровно те байты, которые ему переданы — она не добавляет переносы строк автоматически. Добавляйте \n самостоятельно (внутри двойных кавычек, чтобы управляющая последовательность интерпретировалась):

<?php

$file = fopen('names.txt', 'w');

$names = ['Alice', 'Bob', 'Carol'];
foreach ($names as $name) {
    fwrite($file, $name . PHP_EOL); // PHP_EOL = OS-correct line ending
}

fclose($file);

PHP_EOL принимает значение \n на Unix/macOS и \r\n на Windows, что обеспечивает переносимость текстовых файлов.

Всегда проверяйте возвращаемое значение

Переполнение диска, проблемы с правами доступа и разорванные каналы — всё это может привести к сбою или неполной записи. Используйте возвращаемое значение как источник истины:

<?php

$file = fopen('report.txt', 'w');
if ($file === false) {
    throw new RuntimeException('Unable to open report.txt');
}

$data    = str_repeat('x', 1000);
$written = fwrite($file, $data);

if ($written === false || $written < strlen($data)) {
    fclose($file);
    throw new RuntimeException('Write failed or incomplete');
}

fclose($file);
echo "OK: $written bytes written";

fwrite() и file_put_contents()

Для одиночной записи file_put_contents() короче — она открывает, записывает и закрывает файл в одном вызове:

<?php

// Equivalent of the basic example above, in one line:
file_put_contents('myfile.txt', 'Hello, world!');

Предпочитайте fwrite(), когда нужно держать файл открытым на протяжении многих операций записи (циклы, потоковая передача, логирование), передавать параметры вроде блокировки или писать данные порциями, не собирая всю строку в памяти.

Типичные ошибки

• 'w' немедленно усекает файл — как только fopen($f, 'w') завершается успешно, старое содержимое удалено, даже если вы так и не вызвали fwrite().
• Отсутствие автоматических переносов строк — добавляйте \n / PHP_EOL самостоятельно.
• Забытый fclose() — данные могут оставаться в буфере и никогда не попасть на диск, пока дескриптор не будет закрыт (или скрипт не завершится).
• Одинарные кавычки не раскрывают управляющие последовательности — 'Line\n' записывает буквальный обратный слеш и n. Используйте "Line\n" для настоящего переноса строки.
• Ограничение length задаётся в байтах — при многобайтовом тексте UTF-8 лимит в байтах может разрезать символ пополам.

Заключение

fwrite() — основная функция PHP для записи строк в открытый файл. Освойте трёхшаговый цикл открытие–запись–закрытие, выберите правильный режим fopen() ('w' для замены, 'a' для добавления), добавляйте переносы строк вручную и проверяйте возвращаемое значение — и вы сможете записывать всё: от простых текстовых файлов до надёжных журналов приложений.

Связанные функции

• fopen() — открыть файл перед записью
• fclose() — сбросить буфер и закрыть дескриптор после записи
• fread() и fgets() — считать данные обратно
• file_put_contents() — записать целый файл в одном вызове
• feof() — обнаружить конец файла при чтении

Практика