vsprintf()

Введение

Функция vsprintf() в PHP форматирует строку, используя массив аргументов, и возвращает результат вместо его вывода. Считайте её двойником sprintf() на основе массива: правила форматной строки и плейсхолдеры работают идентично, но значения берутся из одного массива, а не из списка отдельных параметров.

Буква «v» в названии означает vector (массив). Эту функцию стоит использовать, когда ваши значения уже находятся в массиве — например, строка из базы данных, разобранная строка CSV или результат explode() — и вы не хотите передавать их по отдельности.

В этой главе рассматриваются синтаксис, наиболее распространённые спецификаторы формата, реальные случаи форматирования (дополнение символами, числа, переупорядочивание аргументов), а также отличие vsprintf() от связанных функций семейства printf/sprintf.

Синтаксис

vsprintf(string $format, array $values): string

Возвращаемое значение — полностью отформатированная строка. В отличие от vprintf(), ничего не выводится на экран — вы сами решаете, что делать с возвращённым значением.

Примечание: Начиная с PHP 8.0, передача слишком малого количества значений для плейсхолдеров вызывает ValueError. В более ранних версиях генерировалось предупреждение и возвращалось false.

Первый пример

Вывод:

I like apple, banana, and orange.

Каждый плейсхолдер %s заменяется слева направо следующим элементом $values. Готовая строка возвращается и сохраняется в $result — она выводится на экран только потому, что мы явно вызываем echo.

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

Буква после % определяет, как отображается соответствующее значение:

Спецификаторы также могут содержать флаги, ширину и точность между % и буквой (например, %05d или %.2f), что делает vsprintf() по-настоящему мощным инструментом.

Дополнение и форматирование чисел

<?php

// %05d  → pad the integer with zeros to a width of 5
// %01.2f → at least 1 digit, exactly 2 decimal places
// %-10s → left-align the string in a 10-char field
$row = [42, 42.5, 'left'];
echo vsprintf("ID:%05d  Price:\$%01.2f  Name:[%-10s]", $row);

Вывод:

ID:00042  Price:$42.50  Name:[left      ]

Именно для таких случаев обычно выбирают vsprintf(): у вас есть запись (здесь массив $row) и фиксированный шаблон, и вы хотите получить выровненный вывод с дополнением нулями и форматированием валюты без ручной конкатенации строк.

Повторное использование аргументов с позиционными плейсхолдерами

Плейсхолдер вида %n$ ссылается на n-й элемент массива (нумерация с 1), поэтому одно и то же значение можно использовать несколько раз или менять порядок вывода независимо от порядка элементов в массиве:

<?php

$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);

Вывод:

Sam is 30 years old. Hi Sam!

Здесь %1$s используется дважды, хотя 'Sam' присутствует в массиве только один раз.

vsprintf() и другие функции семейства

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

Практическое правило: используйте вариант v*, когда данные уже находятся в массиве, и вариант sprintf/vsprintf (без «print» внутри), когда нужно получить строку обратно, а не немедленно вывести её.

Распространённые ловушки

• Слишком мало значений вызывает ошибку. Если в массиве меньше элементов, чем плейсхолдеров в формате, PHP 8+ выбрасывает ValueError. Убедитесь, что количество элементов массива соответствует числу (непозиционных) спецификаторов.
• Лишние значения игнорируются. Если элементов больше, чем плейсхолдеров — это нормально: излишки просто отбрасываются.
• Ключи игнорируются при последовательных плейсхолдерах. vsprintf() обходит массив по позиции, а не по ключу, поэтому ассоциативный массив читается в порядке вставки.
• Экранируйте буквальные знаки процента как %%, иначе PHP попытается интерпретировать следующий символ как спецификатор.

Связанные функции

• sprintf() — то же форматирование с отдельными аргументами.
• vprintf() — как vsprintf(), но выводит результат напрямую.
• printf() — вывод отформатированной строки из отдельных аргументов.
• number_format() — форматирование чисел с группировкой тысяч.

Практика