vprintf()

Введение

Функция vprintf() в PHP выводит отформатированную строку. Она работает точно так же, как printf(), за исключением того, что значения для подстановки передаются в виде одного массива, а не отдельными аргументами. Буква v в названии означает vector (вектор, массив).

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

Используйте vprintf(), когда значения для форматирования уже находятся в массиве — например, строка из базы данных, результат explode() или список, сформированный динамически. Ручное разворачивание такого массива в printf($fmt, $row[0], $row[1], ...) громоздко и ломается при изменении числа полей; vprintf($fmt, $row) корректно обрабатывает любое количество элементов.

Синтаксис

vprintf(string $format, array $values): int|false

• $format — строка-шаблон, содержащая один или несколько плейсхолдеров. Каждый плейсхолдер начинается со знака процента (%), за которым следует спецификатор преобразования, например s (строка), d (целое число) или f (число с плавающей точкой).
• $values — массив, элементы которого заполняют плейсхолдеры по порядку. Он должен содержать не меньше элементов, чем плейсхолдеров.

vprintf() выводит результат напрямую и возвращает длину выходной строки (тип int) или false в случае ошибки. Если вам нужна отформатированная строка в виде значения, а не вывод, используйте vsprintf().

Базовый пример

Вот простейший случай — три строковых плейсхолдера, заполняемых из массива:

Вывод:

I like apple, banana, and orange.

Каждый %s заменяется по порядку следующим элементом массива $values.

Распространённые спецификаторы формата

Строка формата та же, что используется во всём семействе функций printf. Наиболее полезные спецификаторы:

Между % и спецификатором можно управлять шириной, дополнением, знаком и точностью:

<?php

// Pad an integer to 5 digits with leading zeros, show the sign, print binary.
vprintf("%05d / %+d / %b\n", [42, 7, 5]);

// Left-align in 10 columns, then right-align in 10 columns.
vprintf("%-10s|%10s|\n", ["left", "right"]);

// Money: two decimal places.
vprintf("Total: \$%01.2f\n", [49.9]);

Вывод:

00042 / +7 / 101
left      |     right|
Total: $49.90

Повторное использование значения с нумерацией аргументов

Можно ссылаться на конкретный элемент массива несколько раз с помощью синтаксиса подстановки %n$, где n — позиция, начиная с 1:

<?php

vprintf("Hex of %1\$d is %1\$x\n", [255]);

Вывод:

Hex of 255 is ff

Здесь %1$d и %1$x оба считывают первый элемент массива (255) и форматируют его как десятичное и шестнадцатеричное число соответственно.

Использование возвращаемого значения

vprintf() возвращает количество выведенных символов, что удобно для журналирования или проверки выравнивания:

<?php

$len = vprintf("Total: \$%01.2f\n", [49.9]);
echo "Printed $len characters.\n";

Вывод:

Total: $49.90
Printed 14 characters.

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

Практическое правило: выбирайте версию с v, когда данные находятся в массиве, и версию с s, когда нужно вернуть строку вместо её вывода.

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

• Несоответствие количества. Если в массиве меньше элементов, чем плейсхолдеров, PHP выбрасывает ArgumentCountError (PHP 8+) или предупреждение в более старых версиях. Лишние элементы массива просто игнорируются.
• Экранирование $ в двойных кавычках. Знак доллара перед цифрой (например, $5) может конфликтовать с интерполяцией переменных PHP. Используйте строки формата в одинарных кавычках или экранируйте его как \$, как показано выше.
• Не забывайте, что функция выводит данные. vprintf() немедленно пишет в вывод — возвращаемое значение является длиной, а не строкой. Используйте vsprintf(), чтобы получить результат.
• Ассоциативные массивы. Используются только значения в порядке их хранения; ключи игнорируются. Передавайте список (числовой, последовательный массив), чтобы избежать неожиданностей.

Практика