fprintf()

Введение

Функция fprintf() записывает форматированную строку в поток — файл, php://stdout, php://stderr или любой другой открытый потоковый ресурс — и заполняет её заполнители значениями из списка отдельных аргументов. Буква f в названии означает file (файл): в отличие от printf(), которая выводит результат напрямую, fprintf() отправляет его в выбранный вами поток.

Это член семейства printf, отвечающий за запись в поток. По сравнению с vfprintf() обе функции выполняют абсолютно одинаковую работу, но принимают значения по-разному: fprintf() получает каждое значение отдельным аргументом, а vfprintf() — единым массивом. Используйте fprintf(), когда у вас есть несколько отдельных значений для записи в файл или консоль.

В этой главе рассматриваются синтаксис, спецификаторы формата, исполняемые примеры, сравнение со связанными функциями и типичные ошибки.

Синтаксис

fprintf(resource $stream, string $format, mixed ...$values): int

Функция возвращает количество записанных символов. В современных версиях PHP некорректный вызов вызывает ошибку, а не возвращает false, поэтому проверять возвращаемое значение на наличие ошибки обычно не нужно.

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

Строка $format сочетает литеральный текст с заполнителями, начинающимися с %. Наиболее распространённые спецификаторы:

Между % и буквой типа можно указать ширину, заполнение и точность — например, %05d (дополнить целое число нулями до 5 цифр) или %.2f (два знака после запятой). Буквальный % записывается как %%.

Пример: запись в стандартный вывод

Использование потока php://stdout позволяет сразу увидеть результат, что делает fprintf() удобной для экспериментов:

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Вывод:

Name: John | Age: 30 | Balance: 1234.50

Три аргумента по порядку заполняют %s, %d и %.2f: строка выводится как есть, %d отбрасывает дробную часть целого числа, а %.2f форматирует число с плавающей точкой ровно до двух знаков после запятой.

Пример: запись в файл

Классический случай использования — запись форматированных, выровненных строк в файл, например небольшой журнал:

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Вывод:

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s выравнивает уровень по левому краю в колонке шириной 5 символов, поэтому сообщения начинаются в одной и той же позиции независимо от того, INFO это или ERROR. Открытие файла в режиме "a" (добавление) дописывает каждую строку, не удаляя уже имеющееся содержимое. Каждый вызов fprintf() записывает одну строку, принимая значения как отдельные аргументы.

fprintf() против printf() против vfprintf()

Эти три функции используют абсолютно одинаковые правила строки формата и различаются только тем, куда попадает результат и как передаются значения:

Таким образом, fprintf() — это printf(), которая записывает в поток вместо вывода, и это vfprintf() с отдельными аргументами вместо массива:

// Отдельные аргументы → запись в $stream
fprintf($stream, "%s is %d", $name, $age);

// Те же значения в виде массива → запись в $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Если вам нужна только форматированная строка без записи куда-либо, используйте sprintf(). Распространённый приём с fprintf() в консольных скриптах — запись диагностических сообщений в поток ошибок, чтобы отделить их от обычного вывода:

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR — это предопределённая потоковая константа, доступная в CLI-скриптах PHP, поэтому предварительно открывать её через fopen() не нужно.

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

• Поток указывается первым. Потоковый ресурс — первый аргумент, строка формата — второй. Указание строки формата первой (как в printf()) — самая частая ошибка при переключении между этими функциями.
• Поток должен допускать запись. Открытие файла в режиме "r" (только чтение) и передача его в fprintf() приведёт к ошибке — используйте режим записи, например "w" (перезапись) или "a" (добавление).
• Функция записывает, а не возвращает текст. Возвращаемое значение — количество символов, а не форматированная строка; это частая путаница с sprintf().
• Слишком мало аргументов вызывает ошибку. Передача меньшего числа значений, чем в строке формата спецификаторов, вызывает ArgumentCountError в PHP 8+; лишние значения просто игнорируются.
• Экранируйте буквальные знаки процента как %%, иначе PHP попытается интерпретировать следующий символ как спецификатор.

Заключение

fprintf() форматирует строку и записывает её в поток, принимая значения как отдельные аргументы. Это инструмент выбора, когда нужен точный, колоночный вывод, отправляемый в файл или консоль — строки журнала, отчёты или диагностика CLI через php://stderr. Для связанных вариантов см. printf() (выводит в стандартный вывод), sprintf() (возвращает строку) и vfprintf() (то же назначение, но принимает массив значений).

Практика