vfprintf()

Введение

Функция vfprintf() записывает форматированную строку в поток — например, в файл или стандартный вывод — и берёт значения из массива, а не из списка отдельных аргументов. Префикс v означает vector (массив аргументов), а f — file (запись в поток).

Кратко говоря, vfprintf() относится к fprintf() так же, как vsprintf() относится к sprintf(): выполняет то же форматирование, но принимает один массив вместо перечисления отдельных аргументов. Эту функцию удобно использовать, когда значения уже собраны в массив.

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

Синтаксис

vfprintf(resource $stream, string $format, array $values): int

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

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

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

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

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

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

<?php

$out    = fopen("php://stdout", "w");
$values = ["John", 30, 1234.5];

vfprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", $values);

fclose($out);

Вывод:

Name: John | Age: 30 | Balance: 1234.50

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

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

Основное назначение функции — запись форматированных строк в файл. В этом примере в файл добавляются три строки из массива записей:

<?php

$records = [
    ["Alice", 95],
    ["Bob",   82],
    ["Carol", 77],
];

$file = fopen("scores.txt", "w");

foreach ($records as $row) {
    vfprintf($file, "%-10s %3d%%\n", $row);
}

fclose($file);

echo file_get_contents("scores.txt");

Вывод:

Alice       95%
Bob         82%
Carol       77%

%-10s выравнивает имя по левому краю в колонке шириной 10 символов, %3d — выравнивает счёт по правому краю в колонке шириной 3 символа, а %% выводит буквальный знак процента. Поскольку каждый $row уже является массивом, vfprintf() принимает его напрямую — распаковывать значения не нужно.

Зачем использовать массив? vfprintf() и fprintf()

fprintf() принимает значения как отдельные аргументы:

fprintf($file, "%s is %d", $name, $age);

vfprintf() принимает те же значения в одном массиве:

vfprintf($file, "%s is %d", [$name, $age]);

Используйте vfprintf(), когда значения уже находятся в массиве — например, строка из базы данных, разобранная строка CSV или аргументы, собранные в цикле — чтобы не распаковывать их с помощью оператора расширения (...$row). Если вам нужно получить форматированную строку, а не записывать её в поток, используйте vsprintf(); чтобы напечатать результат прямо в вывод без потокового ресурса, используйте vprintf().

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

• Массив должен содержать не меньше элементов, чем спецификаторов. Слишком мало значений вызывает ArgumentCountError (PHP 8+); лишние значения просто игнорируются.
• Порядок имеет значение. Элементы потребляются позиционно, в порядке следования в массиве. Чтобы обращаться к конкретному элементу вне зависимости от порядка, используйте нумерованные заполнители, например %1$s и %2$d.
• Функция записывает, а не возвращает текст. Возвращаемое значение — количество символов, а не форматированная строка; это частая путаница с vsprintf().
• Поток должен допускать запись. Открытие файла в режиме "r" (только чтение) и передача его в vfprintf() приведёт к ошибке.

Заключение

vfprintf() форматирует строку и записывает её в поток, беря значения из массива. Функция особенно удобна, когда данные уже собраны в массив и их нужно записать в файл или в стандартный вывод в точном, колоночном формате. Для потоконезависимых вариантов см. vsprintf() (возвращает строку) и vprintf() (выводит напрямую), а также сравните с fprintf(), если аргументы передаются по отдельности, а не в массиве.

Практика