vprintf
Prints a formatted string using values from an array and returns the output length.
vprintf(string $format, array $values): int- Added in PHP 4.1.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$format | string | The format string, built from literal text and conversion specifications of the form %[argnum$][flags][width][.precision]specifier. |
$values | array | The values to substitute into the format string, consumed in array order. |
Return value
intThe length in bytes of the string that was output.
Errors
Throws a ValueError if the values array holds fewer items than the format string requires, or if a width or precision is negative or larger than PHP_INT_MAX.
Changelog
- PHP 8.0.0No longer returns false on failure — invalid formats and short values arrays now throw ValueError.
- PHP 8.0.0An invalid [width] or [precision] throws ValueError instead of emitting E_WARNING.
vprintf() is the printing sibling of vsprintf(): it applies a sprintf()-style format to the values in an array and sends the result straight to output instead of returning it. The return value is the byte length of what was printed, not the string.
When to reach for it
Reach for it in CLI scripts and report generators where you are writing line after line and never need the intermediate string — a loop over rows that prints a fixed-width table is the classic case. Because output goes to the standard output buffer, it also works inside output buffering (ob_start()) if you later decide you do want the text.
What trips people up
The most common mistake is treating the return value as the formatted text. $line = vprintf(...) prints the line as a side effect and then leaves an integer in $line; echoing that variable appends a stray number to your output. If you want the string, use vsprintf().
The second is the format string itself. A literal percent needs %%, and positional specifiers such as %1$s must be written in single quotes, otherwise PHP's double-quoted string interpolation eats the $s.
Example
When to use it
- Printing an aligned, fixed-width table row by row in a CLI script.
- Emitting progress lines with percentages and padded counters during a long import.
- Writing a report where each line's values come from a database row array.
Frequently asked questions
What is the difference between vprintf and vsprintf?
vprintf() prints the formatted string immediately and returns its byte length; vsprintf() returns the formatted string and prints nothing. Use vsprintf() whenever you need to store, log, or further process the text.
Why does vprintf print a number after my text?
You echoed its return value. vprintf() already writes the text as a side effect and returns an integer byte count, so `echo vprintf(...)` outputs the line followed by that count. Call it as a statement instead.
Can vprintf write to a file instead of standard output?
No. Use vfprintf(), which takes a stream resource as its first argument and otherwise behaves the same, or capture vprintf() output with ob_start() and ob_get_clean().
More examples
Aligned table output in a loop
The same format string is reused for the header and the data rows, so the columns line up: the name is left-aligned in 12 characters, the quantity right-aligned in 3, and the total right-aligned in 8 with two decimals. Nothing is stored in a variable — each call writes directly to output.
<?php
$rows = [
['espresso', 2, 2.40],
['flat white', 1, 3.80],
['croissant', 3, 2.10],
];
vprintf("%-12s %3s %8s\n", ['item', 'qty', 'total']);
foreach ($rows as $r) {
vprintf("%-12s %3d %8.2f\n", [$r[0], $r[1], $r[1] * $r[2]]);
}Reordering one array with positional specifiers
One array feeds two different sentence orders. Positional specifiers (%1$s, %2$s, %3$d) pick values by index instead of consuming them left to right, which is how you support translated message templates whose word order differs. The format strings are single-quoted and PHP_EOL is concatenated, so the $ signs are never interpolated by PHP.
<?php
$vals = ['2026-08-30', 'deploy', 3];
vprintf('[%1$s] %2$s finished in %3$ds' . PHP_EOL, $vals);
vprintf('%3$d second(s) for %2$s on %1$s' . PHP_EOL, $vals);Padding and literal percent signs
The first line zero-pads 87.5 to a total width of five characters (087.5) and prints a literal percent from %%. The second left-aligns the number in six characters, leaving trailing spaces before the pipe. The third uses the custom padding flag %'*10s to pad with asterisks instead of spaces.
<?php
vprintf("%s usage: %05.1f%%\n", ['disk', 87.5]);
vprintf("%s usage: %-6.1f|\n", ['cpu', 4.25]);
vprintf("%'*10s|\n", ['right']);
Discussion