数字を千の位毎にグループ化してフォーマットする

説明

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

数値を千の位毎にグループ化し、オプションで小数の桁も追加してフォーマットします。小数の桁を追加する場合、四捨五入のルールを使います。

パラメータ

num: フォーマットする数値。
decimals: 小数点以下の桁数。 0 を指定すると、戻り値の decimal_separator は省略されます。 PHP 8.3.0 以降では、この値に負の値を指定すると、 num は小数点前の有効桁数 decimals 桁に丸められるようになりました。これより前のバージョンでは、負の値を指定しても無視され、 0 を指定した場合と同じように処理されていました。
decimal_separator: 小数点を表す区切り文字。
thousands_separator: 千の位毎の区切り文字。

戻り値

num をフォーマットした結果を返します。

変更履歴

バージョン	説明
8.3.0	`decimals` に負の値を指定した場合の処理が追加されました。
8.0.0	これより前のバージョンでは、 number_format() 関数は引数を1個、2個、または4個受け入れていました(つまり、3個はダメでした)。
7.2.0	number_format() は、 `-0` を返さないように変更されました。これより前のバージョンでは、 `num` が `-0.01` のようなケースで `-0` が返される場合がありました。

例

例1 number_format() の例

例えばフランスの表記法では、通常カンマ (',') を小数の区切りとした二桁の小数と、千位毎の区切りとしてスペース (' ') を用います。数値を書式設定するさまざまな方法を次の例で示します。

<?php

$number = 1234.56;

// 英語での表記 (デフォルト)
echo number_format($number), PHP_EOL;
// 1,235

// フランスの表記
echo number_format($number, 2, ',', ' '), PHP_EOL;
// 1 234,56

$number = 1234.5678;

// 千位毎の区切りがない英語での表記
echo number_format($number, 2, '.', ''), PHP_EOL;
// 1234.57

?>

例2 decimals に負の値を指定する

PHP 8.3.0 以降では、decimals に負の値を指定すると、小数点前の有効桁数を丸めるようになりました。

<?php
$number = "1234.5678";
var_dump(number_format($number, -1));
var_dump(number_format($number, -2));
var_dump(number_format($number, -3));
?>

上の例の出力は以下となります。

string(5) "1,230"
string(5) "1,200"
string(5) "1,000"

参考

money_format() - 数値を金額文字列にフォーマットする
sprintf() - フォーマットされた文字列を返す
printf() - フォーマット済みの文字列を出力する
sscanf() - フォーマット文字列に基づき入力を処理する