【PHP8.x】number_format()関数の使い方

Copy
1<?php
2
3/**
4 * 数値をフォーマットし、値が厳密に0の場合は空文字列を返します。
5 * それ以外の数値はnumber_format関数を使用して指定された形式でフォーマットします。
6 *
7 * @param float $num フォーマットする数値。
8 * @param int $decimals 小数点以下の桁数。デフォルトは0。
9 * @param string $decimal_separator 小数点の区切り文字。デフォルトは'.'。
10 * @param string $thousands_separator 千の位の区切り文字。デフォルトは','。
11 * @return string フォーマットされた数値の文字列、または数値が0の場合は空文字列。
12 */
13function formatNumberWithoutZero(
14    float $num,
15    int $decimals = 0,
16    string $decimal_separator = ".",
17    string $thousands_separator = ","
18): string {
19    // 数値が厳密に0の場合、空文字列を返して「0を表示しない」要件に対応します。
20    // 浮動小数点数の比較には注意が必要ですが、ここでは0.0と一致する場合を想定しています。
21    if ($num == 0.0) {
22        return '';
23    }
24
25    // 0以外の数値はnumber_format関数でフォーマットします。
26    return number_format($num, $decimals, $decimal_separator, $thousands_separator);
27}
28
29// --- 使用例 ---
30
31// 0の場合: 空文字列が返されます
32// var_dump(formatNumberWithoutZero(0)); // ''
33
34// 0.00の場合 (小数部指定あり): 空文字列が返されます
35// var_dump(formatNumberWithoutZero(0.00, 2)); // ''
36
37// 正の数の場合: 通常通りフォーマットされます
38// var_dump(formatNumberWithoutZero(12345.678)); // '12,346'
39
40// 負の数の場合: 通常通りフォーマットされます
41// var_dump(formatNumberWithoutZero(-9876.543, 2)); // '-9,876.54'
42
43// 小数部指定あり:
44// var_dump(formatNumberWithoutZero(5000.123, 2)); // '5,000.12'
45
46// 区切り文字を変更した場合:
47// var_dump(formatNumberWithoutZero(1234567.89, 2, ',', ' ')); // '1 234 567,89'
48
49?>

このサンプルコードは、PHPで数値を読みやすい形式に整形する際に、特に「数値が0の場合には何も表示しない」という要件に対応するためのものです。PHP標準のnumber_format関数は、数値を指定された小数点以下の桁数や桁区切り文字を使って文字列に変換しますが、0も通常通り「0」や「0.00」のようにフォーマットしてしまいます。

そこで、提供されているformatNumberWithoutZero関数は、このnumber_format関数を内部で利用しつつ、特定の要件を満たすように拡張しています。この関数は、まず引数として渡された数値$numが厳密に0.0であるかを判定します。もし数値が0であれば、直接空文字列''を戻り値として返します。これにより、画面には何も表示されず、「0を表示しない」という目的が達成されます。

数値が0以外のケースでは、number_format関数に処理を委ねます。この関数は、$num（フォーマットする数値）、$decimals（小数点以下の桁数）、$decimal_separator（小数点の区切り文字）、$thousands_separator（千の位の区切り文字）の引数に基づいて数値を文字列として整形し、その結果を返します。例えば、12345.678が'12,346'になったり、0が空文字列になったりする挙動を示します。この仕組みで、0の時だけ表示を制御し、他の数値は適切に整形することができます。

Copy
1<?php
2
3/**
4 * number_format関数の基本的な使い方と、指定桁数での四捨五入（丸め）の動作を示すサンプルコードです。
5 *
6 * number_format関数は、数値を読みやすい形式にフォーマットし、
7 * 指定された小数点以下の桁数に合わせて数値を丸めます。
8 * PHPのnumber_format関数における丸めは、一般的な四捨五入と同様に、
9 * 対象桁の次が5以上の場合は切り上げ、5未満の場合は切り捨てとなります。
10 */
11
12// 1. 基本的な使い方：小数点以下0桁でフォーマット（デフォルト）
13$value1 = 1234.567;
14// 小数点以下を0桁にすると、小数第一位が5以上なので切り上げられます。
15$formatted_value1 = number_format($value1);
16echo "元の数値: " . $value1 . "\n";
17echo "フォーマット後（0桁、四捨五入）: " . $formatted_value1 . "\n\n"; // 出力: 1,235
18
19$value2 = 1234.499;
20// 小数点以下を0桁にすると、小数第一位が5未満なので切り捨てられます。
21$formatted_value2 = number_format($value2);
22echo "元の数値: " . $value2 . "\n";
23echo "フォーマット後（0桁、四捨五入）: " . $formatted_value2 . "\n\n"; // 出力: 1,234
24
25// 2. 小数点以下の桁数を指定してフォーマット
26$value3 = 9876.54321;
27// 小数点以下を2桁にすると、小数第三位が5未満なので切り捨てられます。
28$formatted_value3 = number_format($value3, 2);
29echo "元の数値: " . $value3 . "\n";
30echo "フォーマット後（2桁、四捨五入）: " . $formatted_value3 . "\n\n"; // 出力: 9,876.54
31
32$value4 = 9876.54567;
33// 小数点以下を2桁にすると、小数第三位が5以上なので切り上げられます。
34$formatted_value4 = number_format($value4, 2);
35echo "元の数値: " . $value4 . "\n";
36echo "フォーマット後（2桁、四捨五入）: " . $formatted_value4 . "\n\n"; // 出力: 9,876.55
37
38// 3. 桁区切り文字と小数点区切り文字をカスタムする例
39$value5 = 1234567.891;
40// 小数点以下を2桁、小数点をカンマ、桁区切りをスペースに指定。
41$formatted_value5 = number_format($value5, 2, ',', ' ');
42echo "元の数値: " . $value5 . "\n";
43echo "フォーマット後（カスタム区切り、2桁）: " . $formatted_value5 . "\n\n"; // 出力: 1 234 567,89
44
45// 4. 四捨五入の挙動が特に分かりやすい例
46$value_round_up = 10.5;
47$value_round_down = 10.49;
48
49echo "元の数値: " . $value_round_up . "\n";
50echo "number_format(" . $value_round_up . ", 0): " . number_format($value_round_up, 0) . " (0.5は切り上げ)\n\n"; // 出力: 11
51
52echo "元の数値: " . $value_round_down . "\n";
53echo "number_format(" . $value_round_down . ", 0): " . number_format($value_round_down, 0) . " (0.49は切り捨て)\n\n"; // 出力: 10
54
55?>

number_format関数は、PHPで数値を人間が読みやすい形式に整形し、指定した小数点以下の桁数で四捨五入を行うための関数です。

この関数は、最初の引数にフォーマットしたい浮動小数点数（float）を受け取ります。2番目の引数には、小数点以下の桁数を整数（int）で指定し、この桁数に合わせて数値が丸められます。PHPのnumber_formatにおける丸めは一般的な四捨五入と同じ挙動を示し、丸めたい桁の次の桁が5以上であれば切り上げ、5未満であれば切り捨てとなります。例えば、小数点以下を0桁に指定した場合、小数第一位が5以上であれば整数部分が繰り上がり、5未満であれば切り捨てとなります。

また、3番目の引数では小数点の区切り文字を、4番目の引数では3桁ごとの桁区切り文字を文字列（string）で任意に設定できます。これらの引数を省略した場合、小数点にはピリオド（.）、桁区切りにはカンマ（,）がデフォルトで使用されます。

最終的に、number_format関数はフォーマットされた数値を文字列（string）として返します。この関数は、金額表示や統計データなど、数値を特定の形式で表示したい場合に非常に役立ちます。

Copy
1<?php
2
3// number_format 関数は、数値を指定された小数点以下の桁数でフォーマットし、文字列として返します。
4// 主に、数値を見やすい形式で表示するために使用されます。
5
6// フォーマットする元の数値
7$originalNumber = 12345.6789;
8
9echo "元の数値: " . $originalNumber . "\n\n";
10
11// --- 小数点以下の桁数を指定する様々な例 ---
12
13// 1. 小数点以下0桁（デフォルトの動作）
14// 第2引数を省略すると、小数点以下0桁で表示され、標準的な四捨五入が行われます。
15$formattedZeroDecimals = number_format($originalNumber);
16echo "小数点以下0桁 (デフォルト): " . $formattedZeroDecimals . "\n";
17// 期待される出力: 12,346 (0.6789 が四捨五入されて 1 になるため)
18
19// 2. 小数点以下2桁に指定
20// 第2引数に 2 を指定すると、小数点以下2桁で表示されます。
21$formattedTwoDecimals = number_format($originalNumber, 2);
22echo "小数点以下2桁: " . $formattedTwoDecimals . "\n";
23// 期待される出力: 12,345.68 (3桁目の 8 が四捨五入されて 7 が 8 になるため)
24
25// 3. 小数点以下4桁に指定
26// 元の数値の小数点以下の桁数 (4桁) と同じ桁数を指定した場合、そのまま表示されます。
27$formattedFourDecimals = number_format($originalNumber, 4);
28echo "小数点以下4桁: " . $formattedFourDecimals . "\n";
29// 期待される出力: 12,345.6789
30
31// 4. 小数点以下6桁に指定
32// 元の数値の小数点以下の桁数 (4桁) より多い桁数 (6桁) を指定した場合、
33// 足りない桁は 0 で埋められます。
34$formattedSixDecimals = number_format($originalNumber, 6);
35echo "小数点以下6桁: " . $formattedSixDecimals . "\n";
36// 期待される出力: 12,345.678900
37
38// 5. 小数点以下1桁に指定
39// 元の数値の小数点以下の桁数より少ない場合、指定された桁数で丸められます。
40$formattedOneDecimal = number_format($originalNumber, 1);
41echo "小数点以下1桁: " . $formattedOneDecimal . "\n";
42// 期待される出力: 12,345.7 (2桁目の 7 が四捨五入されて 6 が 7 になるため)
43
44// number_format関数は、最終的に数値を整形された「文字列」として返すことに注意してください。
45// 計算に使う場合は、整形前の数値を使用するか、文字列を数値型に変換し直す必要があります。
46
47?>

PHPのnumber_format関数は、数値を指定された形式で見やすく整形し、その結果を文字列として返す関数です。主に、金額や統計データなど、数値をユーザーにわかりやすく表示したい場合に利用されます。

この関数は複数の引数を取りますが、最低限必要なのはフォーマットしたい数値（$num）です。第2引数にint $decimalsを指定することで、小数点以下の桁数を制御できます。この引数を省略すると、デフォルトで小数点以下0桁となり、数値を整数に丸めます（標準的な四捨五入が行われます）。

例えば、12345.6789という数値に対して、number_format($originalNumber, 2)のように2を指定すると、小数点以下2桁の12,345.68という文字列が得られます。小数点以下の桁数を元の数値より多く指定した場合は、足りない桁が0で埋められます。逆に、元の桁数より少なく指定した場合は、指定された桁数で四捨五入されます。

注意点として、number_format関数が返すのは整形された「文字列」です。そのため、この関数の結果を直接数値として計算に利用すると予期せぬエラーや誤った結果を招く可能性があります。計算には整形前の元の数値を使用するか、必要に応じて文字列を数値型に変換し直すようにしてください。