file_put_contents()

Функция file_put_contents() записывает строку в файл за один вызов. Это современная однострочная замена классической последовательности fopen() → fwrite() → fclose(): PHP самостоятельно открывает файл, записывает данные и закрывает дескриптор. На этой странице рассмотрены синтаксис, параметры, возвращаемое значение, флаги для дозаписи и блокировки, а также наиболее распространённые ошибки.

Синтаксис

file_put_contents(string $filename, mixed $data, int $flags = 0, ?resource $context = null): int|false

Параметры

Возвращаемое значение

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

Запись в файл

По умолчанию функция перезаписывает существующее содержимое файла (или создаёт файл, если он отсутствует):

<?php

$filename = 'myfile.txt';
$data     = 'This is some data to be written to the file.';

$bytes = file_put_contents($filename, $data);

if ($bytes === false) {
    echo "Failed to write to $filename";
} else {
    echo "Wrote $bytes bytes to $filename";
}

Вывод:

Wrote 44 bytes to myfile.txt

Возвращённое значение 44 — это длина строки в байтах.

Дозапись вместо перезаписи

Передайте флаг FILE_APPEND, чтобы добавлять данные в конец файла вместо замены его содержимого — удобно для лог-файлов:

<?php

$log = 'app.log';

file_put_contents($log, "First line\n", FILE_APPEND);
file_put_contents($log, "Second line\n", FILE_APPEND);

echo file_get_contents($log);

Вывод:

First line
Second line

Без FILE_APPEND второй вызов стёр бы первую строку.

Блокировка файла при записи

Если несколько процессов могут одновременно записывать в один файл, добавьте LOCK_EX для получения эксклюзивной блокировки на время записи. Флаги объединяются оператором побитового ИЛИ (|):

<?php

file_put_contents('counter.txt', "ping\n", FILE_APPEND | LOCK_EX);

Это предотвращает чередование вывода двух процессов и повреждение файла.

Запись array

Если $data является array, его строковые элементы объединяются без разделителя. Добавьте разделители самостоятельно, если они нужны:

<?php

$lines = ['apple', 'banana', 'cherry'];

file_put_contents('fruits.txt', implode("\n", $lines));

echo file_get_contents('fruits.txt');

Вывод:

apple
banana
cherry

Распространённые ошибки

• Молчаливый сбой при проблемах с правами доступа. Если каталог недоступен для записи, вызов возвращает false и выдаёт предупреждение — исключение не выбрасывается. Проверяйте возвращаемое значение (=== false) или оберните вызов и проверьте error_get_last().
• Родительский каталог должен существовать. file_put_contents() создаёт файл, но не отсутствующие каталоги. При необходимости сначала вызовите mkdir($dir, 0777, true).
• FILE_APPEND не то же самое, что перезапись. Забытый флаг — самая частая причина того, что «лог постоянно очищается».
• Пустые данные допустимы. Запись '' возвращает 0, что является ложным значением — используйте === false, чтобы не перепутать успешную запись пустой строки с ошибкой.

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

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

Заключение

file_put_contents() — простейший способ записать строку в файл в PHP: один вызов открывает, записывает и закрывает файл. Используйте FILE_APPEND для дозаписи, LOCK_EX при конкурентной записи и всегда проверяйте успех строгим сравнением === false.

Практика