PHP sprintf(): Format Strings, Padding and Decimals

sprintf() returns a string built from a format and a list of values: each % placeholder in the format is replaced by the next value. sprintf('%s is %d years old', 'Ada', 36) returns "Ada is 36 years old". printf() takes the same arguments but prints the result instead of returning it.

<?php
$name = 'Ada';
$age = 36;
$price = 4.5;

$line = sprintf('%s is %d years old', $name, $age);
echo $line, "\n";

// Two decimals, always
echo sprintf('Total: %.2f EUR', $price), "\n";

// printf prints directly
printf("Order #%05d for %s\n", 42, $name);

The placeholders are filled in order, left to right. %.2f always shows two decimals (4.50, not 4.5), and %05d pads the number with zeros to five digits.

The format specifiers

A placeholder is %, optional modifiers, then one letter for the type:

Change the values below and run it again:

<?php
echo sprintf('%s', 'PHP'), "\n";
echo sprintf('%d', 42.9), "\n";      // the decimals are cut off, not rounded
echo sprintf('%f', 1.5), "\n";
echo sprintf('%.2f', 1.5), "\n";
echo sprintf('%e', 1234.5678), "\n";
echo sprintf('%x %X', 255, 255), "\n";
echo sprintf('%o', 8), "\n";
echo sprintf('%b', 5), "\n";
echo sprintf('%08b', 5), "\n";       // binary padded to 8 bits
echo sprintf('%c', 65), "\n";
echo sprintf('%d%%', 50), "\n";
echo sprintf('%+d %+d', 5, -5), "\n"; // always show the sign

%d truncates a float toward zero, so 42.9 becomes 42. If you want 43, round first: sprintf('%d', round(42.9)). A string that is not a number, such as 'abc', becomes 0 under %d.

Pad with leading zeros

Between % and the letter you can put a padding character and a width. %05d means "pad with 0 to a width of 5". This is the usual way to format order numbers, invoice IDs, times and dates.

<?php
echo sprintf('%05d', 42), "\n";         // 00042
echo sprintf('%03d', 7), "\n";          // 007
echo sprintf('INV-%06d', 1234), "\n";   // INV-001234

// Times and dates from numbers
$h = 9; $m = 5; $s = 3;
echo sprintf('%02d:%02d:%02d', $h, $m, $s), "\n";
echo sprintf('%04d-%02d-%02d', 2026, 3, 14), "\n";

// A width smaller than the number never cuts it
echo sprintf('%03d', 123456), "\n";

The width is a minimum. A number longer than the width is printed in full.

%05.2f: width and decimals together

With floats, the width counts every character of the result, including the decimal point and the minus sign. That is why %05.2f on 3.14159 gives 03.14: five characters in total, two of them after the point.

<?php
$pi = 3.14159;

echo sprintf('%05.2f', $pi), "\n";   // 5 characters in total
echo sprintf('%08.2f', $pi), "\n";   // 8 characters in total
echo sprintf('%.2f', $pi), "\n";     // no width, just 2 decimals
echo sprintf('%.0f', $pi), "\n";     // no decimals
echo sprintf('%.2f', 5), "\n";       // integers get decimals too
echo sprintf('%08.2f', -3.5), "\n";  // the minus sign counts

%f uses the current locale's decimal point (set with setlocale()), while %F always uses a dot. If your code sets a locale and you need a dot for JSON, CSV or an API, use %F.

Align text in columns

A positive width right-aligns, a - before the width left-aligns, and ' followed by a character sets a custom padding character. Combined, they line up plain-text reports and receipts.

<?php
$items = [
    ['Coffee', 2, 3.5],
    ['Croissant', 1, 2.25],
    ['Orange juice', 3, 4],
];

printf("%-14s %3s %8s\n", 'Item', 'Qty', 'Price');
printf("%'-27s\n", '');

$total = 0;
foreach ($items as [$name, $qty, $price]) {
    $line = $qty * $price;
    $total += $line;
    printf("%-14s %3d %8.2f\n", $name, $qty, $line);
}

printf("%'-27s\n", '');
printf("%-14s %12.2f\n", 'Total', $total);
printf("[%'*10s]\n", 'stars');

%-14s pads the item name on the right to 14 characters, %8.2f right-aligns the price in 8 characters, and %'-27s with an empty string prints a line of 27 dashes. %'*10s pads with * instead of spaces.

Number the arguments to reuse or reorder them

%1$s means "the first argument as a string", %2$d "the second as an integer". Numbered placeholders let you use a value twice or change the order without changing the argument list, which translators need when word order differs between languages.

<?php
// Single quotes: in double quotes PHP would read $s as a variable
$format = '%1$s has %2$d new messages. Open them, %1$s?';
echo sprintf($format, 'Ada', 3), "\n";

// Same arguments, different order in the sentence
$en = 'Page %1$d of %2$d';
$ja = '全%2$dページ中%1$dページ目';
echo sprintf($en, 2, 10), "\n";
echo sprintf($ja, 2, 10), "\n";

// Modifiers go after the $
echo sprintf('%1$05.1f / %1$.3f', 2.71828), "\n";

vsprintf, printf and the return values

vsprintf() takes the values as one array, which is handy when they already sit in an array. printf() returns the number of bytes it printed, and vprintf() is the array version of printf().

<?php
$row = ['Ada', 'Lovelace', 1815];
echo vsprintf("%s %s was born in %d.\n", $row);

$bytes = printf("%s\n", 'Hello');
echo "printf printed $bytes bytes\n";

// Same result, two ways
echo sprintf('%.1f%%', 12.345), "\n";
printf("%.1f%%\n", 12.345);

The count from printf() includes the newline, so "Hello\n" is 6 bytes. For multibyte text it counts bytes, not characters.

Too few arguments throws an error

Since PHP 8, a format with more placeholders than values throws an ArgumentCountError instead of returning false. Count the % placeholders (ignoring %%) when you see this error.

<?php
// This throws an ArgumentCountError on purpose: 3 placeholders, 2 values
echo sprintf('%s bought %d items for %.2f', 'Ada', 3);

The message counts the format string as an argument: ArgumentCountError: 4 arguments are required, 3 given. Extra arguments are ignored silently, so the opposite mistake does not show up as an error. If a sprintf result looks wrong, print the format next to the values. When all you need is a thousands separator, number_format() is simpler than building one with sprintf. The full list of modifiers is on php.net.