fputs()

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

Функция fputs() записывает строку в открытый файл. Это основной инструмент для сохранения текста на диск в PHP: логи, экспорты, сгенерированные конфигурационные файлы и так далее.

Самое важное, что нужно знать о fputs() — это псевдоним fwrite(): обе функции полностью идентичны. PHP сохраняет fputs(), поскольку имя читается как «записать строку в файл» (file put string), что привычно для программистов, пришедших из C. В новом коде обычно предпочитают fwrite(), но обе ведут себя одинаково, поэтому всё, описанное ниже, применимо к обоим именам.

Синтаксис

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

• $stream — указатель на файл (ресурс resource), возвращённый функцией fopen(). Это открытый файл, в который выполняется запись, а не имя файла.
• $data — string для записи.
• $length — необязательный параметр. Если указан, запись останавливается после $length байт, даже если $data длиннее.

Функция возвращает количество записанных байт или false при ошибке. Обратите внимание: при отсутствии данных для записи возвращается 0, а не false, поэтому при проверке ошибок всегда используйте ===.

Как использовать функцию fputs()

Запись в файл всегда следует трёхшаговому шаблону:

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

<?php

$file = fopen('myfile.txt', 'w');   // open for writing, truncating the file
fputs($file, "Hello, world!\n");    // write a line
fclose($file);                      // flush + release the handle

После выполнения этого кода myfile.txt будет содержать Hello, world! с переносом строки в конце. \n находится в двойных кавычках, поэтому PHP преобразует его в настоящий перенос строки (буквальный \n в одинарных кавычках будет записан как есть).

Выбор правильного режима fopen()

Режим, передаваемый в fopen(), определяет, куда fputs() будет записывать данные и сохранится ли существующее содержимое. Вот режимы, допускающие запись:

Используйте 'w' для перезаписи и 'a' (добавление в конец) для дозаписи в лог без потери уже имеющихся данных.

<?php

// Append three lines to a log; each run adds to the end.
$log = fopen('app.log', 'a');
fputs($log, "2026-06-21 user logged in\n");
fputs($log, "2026-06-21 report generated\n");
fclose($log);

Ограничение объёма записи

Необязательный третий аргумент ограничивает количество записываемых байт. Это удобно, когда нужен только префикс более длинной строки:

<?php

$file = fopen('clip.txt', 'w');
$written = fputs($file, 'Hello, world!', 5);  // write only the first 5 bytes
fclose($file);

echo $written;   // 5  — the file now contains "Hello"

$written равно 5, а clip.txt содержит только Hello.

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

Запись может завершиться ошибкой: диск переполнен, файл только для чтения или дескриптор закрыт. Поскольку fputs() может законно возвращать 0, проверяйте результат строгим сравнением === false:

<?php

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

if (fputs($file, 'data') === false) {
    echo 'Write failed!';
} else {
    echo 'Write succeeded.';
}

fclose($file);

Это выведет Write succeeded. и позволит избежать классической ошибки, при которой if (!fputs(...)) ошибочно интерпретирует допустимую запись в 0 байт как ошибку.

fputs() и file_put_contents()

fputs() требует открытого дескриптора и идеально подходит для инкрементальной записи (множество небольших записей, например в цикле логирования). Когда нужно просто записать всю строку в файл за один раз, file_put_contents() самостоятельно выполняет открытие, запись и закрытие в одном вызове:

<?php

// Equivalent one-liner — no fopen()/fclose() needed.
file_put_contents('myfile.txt', "Hello, world!\n");

Используйте fputs()/fwrite(), когда нужен контроль над дескриптором (дозапись в несколько вызовов, частичная запись); используйте file_put_contents() для однократной записи.

Итоги

• fputs() — псевдоним fwrite(): одинаковое поведение, два имени.
• Функция записывает в открытый указатель на файл, возвращённый fopen(), поэтому всегда используйте её в паре с fclose().
• Возвращает количество байт или false при ошибке — проверяйте через === false.
• Используйте 'w' для перезаписи и 'a' для дозаписи; необязательная длина ограничивает количество записываемых байт.
• Для однократной записи всего содержимого предпочтительнее file_put_contents(). Чтобы прочитать данные обратно, см. fgets() и fread().

Практика