Описание

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

Функция работает так же, как последовательный вызов функций fopen(), fwrite() и fclose() для записи данных в файл.

Если путь filename не существует, функция создаст файл. В противном случае она перезапишет существующий файл, если не установлен флаг FILE_APPEND.

Список параметров

filename

Путь к файлу, в который функция будет записывать данные.

data

Записываемые данные. Разрешено передавать строку (string), массив (array) или ресурс потока.

Если данные data — ресурс потока (stream), функция скопирует оставшийся буфер потока в файл. Это похоже на работу функции stream_copy_to_stream().

Допустимо определять параметр data как одномерный массив. Это будет эквивалентно вызову file_put_contents($filename, implode('', $array)).

flags

В параметр flags разрешено передавать произвольные комбинации следующих флагов, соединяя их бинарным оператором ИЛИ (|).

Доступные флаги

Флаг Описание

FILE_USE_INCLUDE_PATH Ищет файл filename во включённых каталогах. Параграф include_path даёт дополнительную информацию.

FILE_APPEND Функция допишет данные в конец файла вместо того, чтобы перезаписать его, если файл filename уже существует.

LOCK_EX Получает эксклюзивную блокировку файла на время записи. Другими словами, между вызовами функций fopen() и fwrite() произойдёт вызов функции flock(). Это не тождественно вызову функции fopen() с флагом «x».

context

**Доступные флаги**
Флаг	Описание
`FILE_USE_INCLUDE_PATH`	Ищет файл `filename` во включённых каталогах. Параграф include_path даёт дополнительную информацию.
`FILE_APPEND`	Функция допишет данные в конец файла вместо того, чтобы перезаписать его, если файл `filename` уже существует.
`LOCK_EX`	Получает эксклюзивную блокировку файла на время записи. Другими словами, между вызовами функций fopen() и fwrite() произойдёт вызов функции flock(). Это не тождественно вызову функции fopen() с флагом «x».

Допустимый ресурс контекста, который создан функцией stream_context_create().

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

Функция возвращает количество байтов, которые процесс записал в файл, или false в случае ошибки.

Внимание

Функция возвращает как логическое значение false, так и нелогическое значение, которое приводится к false. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

Примеры

Пример #1 Пример простого использования

<?php

$file = 'people.txt';

// Открываем файл, чтобы получить существующее содержимое
$current = file_get_contents($file);

// Добавляем нового человека в файл
$current .= "Джон Смит\n";

// Записываем содержимое обратно в файл
file_put_contents($file, $current);

?>

Пример #2 Использование флагов

<?php

$file = 'people.txt';

// Новый человек, которого нужно добавить в файл
$person = "Джон Смит\n";

// Записываем содержимое в файл
// с флагом FILE_APPEND, чтобы дописать содержимое в конец файла,
// и флагом LOCK_EX, чтобы никто другой не мог записывать данные в файл в то же самое время
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);

?>

Примечания

Замечание: Функция безопасна для обработки данных в двоичной форме.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

Смотрите также

fopen() - Открывает файл или URL-адрес
fwrite() - Записывает данные в файл в бинарно-безопасном режиме
file_get_contents() - Считывает содержимое файла в строку
stream_context_create() - Создаёт контекст потока