vfprintf()

Introduction

The vfprintf() function writes a formatted string to a stream — like a file or standard output — and takes its values from an array instead of a list of separate arguments. The leading v stands for vector (an array of arguments); the f stands for file (it targets a stream).

In short, vfprintf() is to fprintf() what vsprintf() is to sprintf(): it does the same formatting, but you hand it one array rather than spelling out each argument. This is the function you reach for when the values are already collected in an array.

This chapter covers the syntax, the format specifiers, runnable examples, when to choose it over the alternatives, and common gotchas.

Syntax

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

It returns the number of characters written. On most PHP versions a malformed call raises an error rather than returning false, so you don't normally test the return value for failure.

Format specifiers

The $format string mixes literal text with placeholders that begin with %. The most common specifiers are:

You can add width, padding, and precision between the % and the type letter — for example %05d (pad an integer to 5 digits with zeros) or %.2f (two decimal places). A literal % must be written as %%.

Example: writing to standard output

Using the php://stdout stream lets you see the result immediately, which makes vfprintf() easy to try:

<?php

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

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

fclose($out);

Output:

Name: John | Age: 30 | Balance: 1234.50

The three array elements fill %s, %d, and %.2f in order: the string is printed as-is, %d drops the decimal part of an integer, and %.2f formats the float to exactly two decimal places.

Example: writing to a file

The original use case is writing formatted lines to a file. Here we append three rows pulled from an array of records:

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

Output:

Alice       95%
Bob         82%
Carol       77%

%-10s left-aligns the name in a 10-character column, %3d right-aligns the score in a 3-character column, and %% prints the literal percent sign. Because each $row is already an array, vfprintf() consumes it directly — no need to unpack the values.

Why use an array? vfprintf() vs fprintf()

fprintf() takes its values as separate arguments:

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

vfprintf() takes the same values in a single array:

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

Reach for vfprintf() when the values are already in an array — for example a database row, a parsed CSV line, or arguments built up in a loop — so you don't have to unpack them with the spread operator (...$row). If you simply want the formatted string back instead of writing it to a stream, use vsprintf(); to print straight to output without a stream resource, use vprintf().

Common gotchas

• The array must have at least as many elements as specifiers. Too few values triggers an ArgumentCountError (PHP 8+); extra values are simply ignored.
• Order matters. Elements are consumed positionally, in array order. To reference a specific element regardless of order, use numbered placeholders like %1$s and %2$d.
• It writes, it doesn't return text. The return value is a character count, not the formatted string — a frequent mix-up with vsprintf().
• The stream must be writable. Opening a file with "r" (read mode) and passing it to vfprintf() fails.

Conclusion

vfprintf() formats a string and writes it to a stream, taking its values from an array. It shines when your data is already collected in an array and you want it written to a file or to standard output in a precise, columnar format. For the non-stream variants, see vsprintf() (returns a string) and vprintf() (prints directly), and compare with fprintf() when your arguments are separate values rather than an array.

Practice