PHP number_format(): separador de milhar e casas decimais

number_format($number, $decimals) retorna o número como string com um separador de milhar e um número fixo de casas decimais: number_format(1234567.891, 2) retorna "1,234,567.89". Com um argumento, ele arredonda para um número inteiro: 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";

Os quatro parâmetros

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

O terceiro argumento é o caractere entre a parte inteira e as casas decimais, o quarto o caractere entre os grupos de três dígitos. Qualquer um deles pode ser qualquer string, inclusive vazia ou um caractere multibyte. Edite os separadores abaixo para ver cada estilo:

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

Os dados de locale (CLDR) usam um espaço estreito não separável (U+202F) para o francês e um espaço não separável (U+00A0) para o russo, para que um número nunca seja quebrado em duas linhas. No HTML, passe "\u{202F}" ou "\u{00A0}" como separador em vez de um espaço comum.

Formatar um número sem separador de milhar

Passe '' como quarto argumento. Você recebe um número simples com um número fixo de casas decimais, o formato que gateways de pagamento, exportações CSV e valores de <input type="number"> esperam:

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

Na última linha, o round() antes do cast importa: 19.9 * 100 é guardado como 1989.9999999999998, e só o (int) o cortaria para 1989.

Como o number_format arredonda

O number_format() arredonda a metade para longe do zero, como o round(), então 0.5 vira 1 e -2.5 vira -3. Ele também corrige o pequeno erro binário de valores como 2.675, e é por isso que pode discordar do 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 não pode ser guardado com exatidão em binário; o valor guardado fica um pouquinho abaixo. O sprintf() formata esse valor guardado e dá 2.67, enquanto o number_format() e o round() o tratam como o 2.675 que você escreveu. Se precisar de uma regra de arredondamento específica, chame round(), floor() ou ceil() você mesmo antes (veja arredondamento e matemática) e passe o resultado para o number_format().

Formatar dinheiro e outras moedas

O number_format() não sabe nada de moedas, então você adiciona o símbolo. Coloque o sinal de negativo antes do símbolo, e lembre que o iene não tem casas decimais:

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

Para uma saída que respeita o locale, com a posição certa do símbolo para cada país, o NumberFormatter da extensão intl faz o trabalho todo:

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

Ele exige a extensão intl, que não está instalada em todo lugar, então o number_format() com o seu próprio símbolo é a escolha portável.

O resultado é uma string, não um número

Esse é o bug mais comum com o number_format(): formatar um valor e depois calcular com ele. "1,234.50" não é uma string numérica, então o PHP lê só o 1 antes da vírgula:

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

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

Passar uma string dessas de volta para o number_format() é pior: ele lança TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Guarde o número cru para as contas e formate só no momento de imprimir. Se você recebe uma string formatada de um formulário ou de um arquivo, tire os separadores antes:

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

Para preenchimento, alinhamento ou um sinal de mais na frente do número, use o sprintf(); ele não adiciona separadores de milhar, mas controla largura e sinal.