PHP number_format(): 천 단위 콤마와 소수점

number_format($number, $decimals)는 천 단위 구분 기호와 고정된 소수점 자리를 가진 문자열로 숫자를 반환합니다: number_format(1234567.891, 2)는 "1,234,567.89"를 반환합니다. 인수가 하나면 정수로 반올림합니다: 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";

네 가지 매개변수

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

세 번째 인수는 정수 부분과 소수 부분 사이의 문자이고, 네 번째는 세 자리 묶음 사이의 문자입니다. 둘 다 빈 문자열이나 멀티바이트 문자를 포함해 어떤 문자열이든 될 수 있습니다. 아래에서 구분 기호를 바꿔 각 스타일을 확인해 보세요.

<?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)는 숫자가 두 줄로 나뉘지 않도록 프랑스어에는 좁은 줄 바꿈 없는 공백(U+202F)을, 러시아어에는 줄 바꿈 없는 공백(U+00A0)을 씁니다. HTML에서는 일반 공백 대신 "\u{202F}"나 "\u{00A0}"을 구분 기호로 넘기세요.

천 단위 구분 기호 없이 숫자 포맷하기

네 번째 인수로 ''를 넘기세요. 고정된 소수점 자리를 가진 평범한 숫자가 되며, 결제 게이트웨이, 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 같은 값의 아주 작은 이진 오차도 보정하므로 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는 이진수로 정확히 저장할 수 없고, 저장된 값은 그보다 아주 조금 작습니다. 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()를 쓰세요. 천 단위 구분 기호는 넣지 않지만 폭과 부호를 제어합니다.