vsprintf()

Introduction

The vsprintf() function in PHP formats a string using an array of arguments and returns the result instead of printing it. Think of it as the array-based twin of sprintf(): the format string and placeholders work identically, but the values come from one array rather than from a list of separate parameters.

The "v" in the name stands for vector (array). This is the function to reach for when your values already live in an array — for example a database row, a parsed CSV line, or the result of explode() — and you don't want to spread them out into individual arguments.

This chapter covers the syntax, the most common format specifiers, real formatting cases (padding, numbers, argument reordering), and how vsprintf() differs from the related printf/sprintf family.

Syntax

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

The return value is the fully formatted string. Unlike vprintf(), nothing is sent to the output — you decide what to do with the returned value.

Note: As of PHP 8.0, passing too few values for the placeholders throws a ValueError. In earlier versions it raised a warning and returned false.

A first example

Output:

I like apple, banana, and orange.

Each %s placeholder is replaced, left to right, with the next element of $values. The finished string is returned and stored in $result — it is only printed because we explicitly call echo.

Common format specifiers

The letter after % controls how the matching value is rendered:

Specifiers can also carry flags, a width, and a precision between the % and the letter (for example %05d or %.2f), which is where vsprintf() becomes genuinely powerful.

Padding and number formatting

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

Output:

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

This is the typical reason to choose vsprintf(): you have a record (here a $row array) and a fixed template, and you want aligned, zero-padded, currency-style output without concatenating strings by hand.

Reusing arguments with positional placeholders

A placeholder of the form %n$ refers to the n-th element of the array (1-based), so you can use the same value more than once or change its order independently of the array:

<?php

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

Output:

Sam is 30 years old. Hi Sam!

Here %1$s is used twice, even though 'Sam' appears only once in the array.

vsprintf() vs. the rest of the family

These four functions share the exact same format-string rules; they differ only in how arguments are passed and what they do with the result:

So the rule of thumb is: use a v* variant when your data is already in an array, and use the sprintf/vsprintf (without the inner print) variants when you want the string back instead of immediate output.

Common gotchas

• Too few values throw an error. If the array has fewer elements than the format has placeholders, PHP 8+ throws a ValueError. Make sure the array length matches the number of (non-positional) specifiers.
• Extra values are ignored. More elements than placeholders is fine — the surplus is silently dropped.
• Keys are ignored for sequential placeholders. vsprintf() consumes the array by position, not by key, so an associative array is read in insertion order.
• Escape literal percent signs as %%, otherwise PHP tries to read the following character as a specifier.

Related functions

• sprintf() — same formatting with separate arguments.
• vprintf() — like vsprintf() but prints the result directly.
• printf() — print a formatted string from separate arguments.
• number_format() — format numbers with grouped thousands.

Practice