PHPのnumber_format()：3桁カンマ区切りと小数点

number_format($number, $decimals)は、3桁ごとの区切りと固定の小数点以下の桁数を付けた文字列として数値を返します：number_format(1234567.891, 2)は"1,234,567.89"を返します。引数が1つなら整数に丸めます：number_format(1234567.891)は"1,234,568"です。

<?php
$amount = 1234567.891;

echo number_format($amount), "\n";            // no decimals
echo number_format($amount, 2), "\n";         // 2 decimals
echo number_format($amount, 2, ',', '.'), "\n"; // European style
echo number_format(0.129, 2), "\n";
echo number_format(-1234.567, 1), "\n";

4つの引数

number_format(
    float $num,
    int $decimals = 0,
    ?string $decimal_separator = ".",
    ?string $thousands_separator = ","
): string

3つ目の引数は整数部分と小数部分の間の文字、4つ目は3桁ごとのグループの間の文字です。どちらも、空文字列やマルチバイト文字を含め、どんな文字列でもかまいません。下の区切り文字を編集して、それぞれの書式を確認してください。

<?php
$n = 1234567.891;

echo number_format($n, 2, '.', ','), "  US, UK, Japan\n";
echo number_format($n, 2, ',', '.'), "  Germany, Spain, Italy, Brazil\n";
echo number_format($n, 2, ',', ' '), "  France, Russia, Poland\n";
echo number_format($n, 2, '.', "'"), "  Switzerland\n";
echo number_format($n, 2, '.', ''), "  no separator\n";

ロケールのデータ（CLDR）では、数値が2行に分かれないよう、フランス語には細いノーブレークスペース（U+202F）が、ロシア語にはノーブレークスペース（U+00A0）が使われます。HTMLでは、普通の空白の代わりに"\u{202F}"や"\u{00A0}"を区切り文字として渡します。

桁区切りなしで数値を整形する

4つ目の引数に''を渡します。小数点以下の桁数が固定された素の数値になり、決済ゲートウェイ、CSVのエクスポート、<input type="number">の値が期待する形です。

<?php
$prices = [5, 19.9, 1234.5];

foreach ($prices as $p) {
    echo number_format($p, 2, '.', ''), "\n";
}

// Cents as an integer, for APIs that want the smallest unit
echo (int) round(19.9 * 100), "\n";

最後の行では、キャストの前のround()が重要です。19.9 * 100は1989.9999999999998として保存されるので、(int)だけだと1989に切り捨てられてしまいます。

number_formatの丸め方

number_format()はround()と同じく0から遠い方向へ丸めるので、0.5は1に、-2.5は-3になります。また2.675のような値のわずかな2進数の誤差も補正するので、sprintf('%.2f')と結果が食い違うことがあります。

<?php
foreach ([0.5, 1.5, 2.5, -2.5] as $x) {
    echo $x, " => ", number_format($x), "\n";
}

echo "\n";
echo number_format(2.675, 2), "  number_format\n";
echo sprintf('%.2f', 2.675), "  sprintf\n";
echo round(2.675, 2), "  round\n";

// PHP 8.3: negative decimals round to tens, hundreds, thousands
echo number_format(1234567, -3), "\n";

2.675は2進数で正確に保存できず、保存される値はわずかに小さくなります。sprintf()は保存された値を整形して2.67になり、number_format()とround()は書いたとおりの2.675として扱います。特定の丸め方が必要なら、先に自分でround()、floor()、ceil()を呼び（丸めと数学関数を参照）、その結果をnumber_format()に渡します。

金額やほかの通貨を整形する

number_format()は通貨について何も知らないので、記号は自分で付けます。マイナス記号は通貨記号の前に置き、円には小数部分がないことを覚えておきましょう。

<?php
function money(float $amount, string $symbol = '$'): string
{
    $sign = $amount < 0 ? '-' : '';
    return $sign . $symbol . number_format(abs($amount), 2);
}

echo money(1499.5), "\n";
echo money(-20), "\n";
echo money(1234.5, '€'), "\n";

// Japanese yen: no decimals, 円 after the number
echo number_format(1980), "円\n";
echo '¥' . number_format(128000), "\n";

あらゆる国について記号の位置が正しい、ロケールに対応した出力には、intl拡張のNumberFormatterがすべてを引き受けてくれます。

$fmt = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(1234.5, 'EUR'); // 1.234,50 € (a no-break space before €)

これにはintl拡張が必要で、どこにでも入っているわけではないので、自分で記号を付けるnumber_format()が移植性の高い選択です。

結果は数値ではなく文字列

number_format()でいちばんよくあるバグは、値を整形してからそれで計算することです。"1,234.50"は数値文字列ではないので、PHPはカンマの前の1しか読みません。

<?php
echo number_format(1234.5, 2) + 1;

Warning: A non-numeric value encountered in /home/index.php on line 2
2

そのような文字列をnumber_format()に渡し直すのはさらに悪く、TypeError: number_format(): Argument #1 ($num) must be of type int|float, string givenが投げられます。計算には元の数値を残しておき、出力する瞬間にだけ整形しましょう。フォームやファイルから整形済みの文字列を受け取ったら、先に区切り文字を取り除きます。

<?php
$total = 1234.5;
$display = number_format($total, 2);      // for output only

echo $display, "\n";
echo number_format($total + 100, 2), "\n"; // math on the number, then format

// Turning "1,234.50" back into a float
$input = '1,234.50';
$value = (float) str_replace(',', '', $input);
var_dump($value);

// European input "1.234,50"
$eu = '1.234,50';
$value = (float) str_replace(['.', ','], ['', '.'], $eu);
var_dump($value);

パディング、位置揃え、数値の前のプラス記号が必要なら、代わりにsprintf()を使います。桁区切りは付けませんが、幅と符号を制御できます。