fprint()

Функция PHP fprintf() записывает форматированную строку в открытый файл (поток). Думайте о ней как о printf() — которая выводит данные в браузер/вывод — но с перенаправлением в файловый дескриптор. Это идеальный выбор, когда нужно записывать чистый, выровненный и предсказуемый текст в лог-файл или генерируемый отчёт, вместо ручного формирования строк через конкатенацию.

На этой странице рассмотрены синтаксис, наиболее часто используемые спецификаторы формата, два полных примера с запуском и родственные функции, которые можно использовать вместо неё.

Синтаксис

int fprintf ( resource $handle , string $format [, mixed ...$args ] )

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

Спецификаторы формата

Мощь fprintf() заключается в строке $format. Каждый символ % вводит заполнитель:

Те же спецификаторы работают в printf() и sprintf(), поэтому, освоив их здесь, вы сможете применять их повсюду.

Запись отчёта

Ниже приведён полный пример, записывающий небольшой отчёт в файл.

<?php
$file = fopen("report.txt", "w");
if ($file === false) {
    die("Failed to open file");
}
$name = "John";
$age = 30;
$income = 50000;
// \$ prints a literal dollar sign; %.2f rounds the float to 2 decimals
$bytes = fprintf($file, "Name: %s\nAge: %d\nIncome: \$%.2f", $name, $age, $income / 12);
fclose($file);

echo "$bytes bytes written"; // 35 bytes written
?>

Мы открываем report.txt для записи ("w") и проверяем, что fopen() не завершился ошибкой. Затем fprintf() подставляет каждую переменную в строку формата: %s — для имени, %d — для возраста и \$%.2f — для ежемесячного дохода (литеральный $ за которым следует число с плавающей точкой, округлённое до двух знаков). Всегда вызывайте fclose() по завершении работы, чтобы буфер был сброшен на диск и дескриптор освобождён.

Результирующий файл report.txt содержит:

Name: John
Age: 30
Income: $4166.67

50000 / 12 равно 4166.6667, и %.2f округляет это до 4166.67.

Дозапись в лог-файл

Очень распространённый случай использования — дозапись одной форматированной строки в лог. Откройте файл в режиме дозаписи ("a"), чтобы каждый вызов добавлял новую строку вместо перезаписи существующего содержимого:

<?php
$file = fopen("error.log", "a");
if ($file === false) {
    die("Failed to open file");
}
$error_code = 404;
$date = date("Y-m-d H:i:s");
$ip_address = $_SERVER['REMOTE_ADDR'];
fprintf($file, "[%s] Error %d from IP address %s\n", $date, $error_code, $ip_address);
fclose($file);
?>

Поскольку файл открыт с флагом "a", каждый запуск добавляет новую строку; ничего из уже записанного в error.log не теряется. Символ \n в конце строки формата помещает каждую запись на отдельную строку. Типичная добавленная строка выглядит так:

[2023-03-15 15:30:00] Error 404 from IP address 192.168.0.1

fprintf() и связанные функции

Выбор правильного инструмента делает код понятнее:

• printf() — то же форматирование, но вывод идёт в стандартный поток вывода (браузер/CLI), а не в файл.
• sprintf() — возвращает форматированную строку вместо записи куда-либо, что позволяет сохранить или повторно использовать её.
• fwrite() — записывает сырые байты в файл без форматирования; используйте, когда заполнители % не нужны.
• vfprintf() — аналог fprintf(), но принимает аргументы в виде одного array вместо переменного числа аргументов.

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

• Несоответствие спецификаторов и аргументов. %d применённый к нечисловой строке даёт 0; передача меньшего числа аргументов, чем заполнителей, вызывает предупреждение.
• Забытое экранирование %. Чтобы вывести литеральный знак процента, используйте %%, а не %.
• Забытый fclose(). Буферизованные данные могут не быть сброшены на диск до закрытия дескриптора (или завершения скрипта).
• Важность режима открытия. "w" очищает файл; "a" выполняет дозапись. Выбирайте осознанно.

Практика