PHPのsprintf()：書式指定、ゼロ埋め、小数点の桁数

sprintf()は、書式と値のリストから組み立てた文字列を返します。書式の中の%のプレースホルダーが、それぞれ次の値に置き換えられます。sprintf('%s is %d years old', 'Ada', 36)は"Ada is 36 years old"を返します。printf()は同じ引数を受け取りますが、結果を返す代わりに出力します。

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

プレースホルダーは左から右へ順に埋められます。%.2fは常に小数点以下2桁を表示し（4.5ではなく4.50）、%05dは数値を5桁になるまでゼロで埋めます。

書式指定子

プレースホルダーは、%、任意の修飾子、型を表す1文字の順に書きます。

下の値を変えて、もう一度実行してみてください。

<?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はfloatを0の方向に切り捨てるので、42.9は42になります。43にしたいなら、先に丸めます：sprintf('%d', round(42.9))。'abc'のような数値でない文字列は、%dでは0になります。

ゼロ埋めする

%と型の文字の間には、埋める文字と幅を書けます。%05dは「幅5まで0で埋める」という意味です。注文番号、請求書のID、時刻、日付を整形する定番の方法です。

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

幅は最小値です。幅より長い数値はそのまま全部出力されます。

%05.2f：幅と小数点以下の桁数を一緒に指定する

floatでは、幅は小数点やマイナス記号も含め、結果のすべての文字を数えます。そのため3.14159に%05.2fを使うと03.14になります。全体で5文字、そのうち2文字が小数点以下です。

<?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は現在のロケール（setlocale()で設定）の小数点を使いますが、%Fは常にドットを使います。コードでロケールを設定していて、JSON、CSV、APIのためにドットが必要なら%Fを使いましょう。

テキストを列に揃える

正の幅は右揃え、幅の前の-は左揃え、'のあとに文字を書くと埋める文字を指定できます。組み合わせれば、プレーンテキストのレポートやレシートの列を揃えられます。

<?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は商品名を右側で14文字まで埋め、%8.2fは価格を8文字の中で右揃えにし、空文字列に対する%'-27sは27個のダッシュの線を出力します。%'*10sは空白の代わりに*で埋めます。

引数に番号を付けて再利用や並べ替えをする

%1$sは「1つ目の引数を文字列として」、%2$dは「2つ目を整数として」の意味です。番号付きのプレースホルダーを使えば、引数のリストを変えずに値を2回使ったり順番を変えたりでき、言語によって語順が違う場合に翻訳者が必要とする機能です。

<?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と戻り値

vsprintf()は値を1つの配列で受け取るので、値がすでに配列に入っているときに便利です。printf()は出力したバイト数を返し、vprintf()は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);

printf()の数には改行も含まれるので、"Hello\n"は6バイトです。マルチバイトのテキストでは、文字ではなくバイトを数えます。

引数が足りないとエラーが投げられる

PHP 8以降、値よりプレースホルダーが多い書式は、falseを返す代わりにArgumentCountErrorを投げます。このエラーが出たら、%のプレースホルダー（%%は除く）を数えてください。

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

メッセージは書式の文字列も引数として数えます：ArgumentCountError: 4 arguments are required, 3 given。余分な引数は黙って無視されるので、逆のミスはエラーとして表れません。sprintfの結果がおかしく見えたら、書式と値を並べて出力してみましょう。桁区切りのカンマだけが必要なら、sprintfで作るよりnumber_format()のほうが簡単です。修飾子の完全な一覧はphp.netにあります。