vprintf()

Introduction

The vprintf() function in PHP outputs a formatted string. It behaves exactly like printf(), except that the values to substitute are supplied as a single array instead of as separate arguments. The v in the name stands for vector (array).

This page covers the syntax, the format specifiers you can use, a set of runnable examples, the differences from related functions, and the common mistakes to avoid.

Reach for vprintf() when the values you need to format already live in an array — for example, a database row, the result of explode(), or a list you built dynamically. Spreading such an array manually into printf($fmt, $row[0], $row[1], ...) is verbose and breaks the moment the number of fields changes; vprintf($fmt, $row) handles any count cleanly.

Syntax

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

• $format — a template string containing one or more placeholders. Each placeholder begins with a percent sign (%) followed by a conversion specifier such as s (string), d (integer), or f (float).
• $values — an array whose elements fill the placeholders, in order. It should contain at least as many elements as there are placeholders.

vprintf() prints the result directly and returns the length of the output string (an int), or false on failure. If you need the formatted string as a value instead of printing it, use vsprintf().

Basic example

Here is the simplest case — three string placeholders filled from an array:

This will output:

I like apple, banana, and orange.

Each %s is replaced, in order, by the next element of $values.

Common format specifiers

The format string is the same one used across the whole printf family. The most useful specifiers are:

You can also control width, padding, sign, and precision between the % and the specifier:

<?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]);

Output:

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

Reusing one value with argument numbering

You can reference a specific array element more than once with the %n$ swapping syntax, where n is the 1-based position:

<?php

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

Output:

Hex of 255 is ff

Here %1$d and %1$x both read the first array element (255) and format it as decimal and hexadecimal respectively.

Using the return value

vprintf() returns the number of characters it printed, which is handy for logging or alignment checks:

<?php

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

Output:

Total: $49.90
Printed 14 characters.

vprintf() vs. related functions

Rule of thumb: choose the v version when your data is in an array, and the s version when you want the string returned instead of echoed.

Common gotchas

• Mismatched counts. If the array has fewer elements than there are placeholders, PHP raises an ArgumentCountError (PHP 8+) or a warning on older versions. Extra array elements are simply ignored.
• Escaping $ in double quotes. A literal dollar sign before a digit (as in $5) can collide with PHP variable interpolation. Either use single-quoted format strings or escape it as \$, as shown above.
• Forgetting it echoes. vprintf() writes to the output immediately — its return value is a length, not the string. Use vsprintf() to capture the result.
• Associative arrays. Only the values are used, in their stored order; keys are ignored. Pass a list (numeric, sequential array) to avoid surprises.

Practice