number_format()

A função PHP number_format() formata um número com agrupamento de milhares e um número opcional fixo de casas decimais. Ela retorna uma string, o que a torna a função ideal para exibir preços, estatísticas e qualquer número que um humano irá ler. Trata-se puramente de apresentação: não altera o valor subjacente, apenas a forma como ele é renderizado.

Este capítulo aborda a sintaxe, cada parâmetro, como o arredondamento funciona e os erros comuns a observar.

Sintaxe

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

Parâmetros

A função sempre retorna uma string, portanto o resultado está pronto para imprimir ou concatenar, mas não deve ser usado para operações aritméticas posteriores.

Exemplo básico

Com apenas o número fornecido, number_format() arredonda para um número inteiro e adiciona vírgulas entre os milhares:

Saída:

1,235

A parte fracionária .56 fez com que o valor fosse arredondado para 1235, e uma vírgula foi inserida entre os milhares.

Controlando as casas decimais

Passe um segundo argumento para manter um número fixo de casas decimais. Isso é quase sempre o que se quer para valores monetários:

<?php
echo number_format(1234.567, 2);  // two decimal places
?>

Saída:

1,234.57

O terceiro decimal (7) é arredondado para a segunda casa. Note que o número de casas decimais é fixo mesmo quando o valor original tem menos — number_format(5, 2) retorna "5.00".

Separadores personalizados (formatos internacionais)

O terceiro e o quarto argumentos permitem trocar os separadores. Muitas localidades europeias usam ponto para os milhares e vírgula para o separador decimal:

<?php
$amount = 1234567.891;

echo number_format($amount, 2, ".", ",") . "\n";  // US / UK style
echo number_format($amount, 2, ",", ".") . "\n";  // German / Spanish style
echo number_format($amount, 2, ".", " ");         // space-grouped
?>

Saída:

1,234,567.89
1.234.567,89
1 234 567.89

Para remover completamente o agrupamento de milhares, passe uma string vazia como quarto argumento:

<?php
echo number_format(1234567.891, 2, ".", "");
?>

Saída:

1234567.89

Como o arredondamento funciona

number_format() arredonda o valor para a precisão solicitada usando o método arredondamento meio afastado do zero — o mesmo padrão da função round(). Um .5 final é arredondado para cima em magnitude:

<?php
echo number_format(2.5) . "\n";   // 3
echo number_format(0.5) . "\n";   // 1
echo number_format(-9.5);         // -10
?>

Saída:

3
1
-10

Erros comuns

• O resultado é uma string, não um número. Adicionar o separador de milhares significa que "1,235" + 1 não se comportará como aritmética. Se precisar continuar calculando com o valor, formate-o apenas no momento de exibi-lo. Para converter uma entrada do usuário que contenha separadores de volta em número, use floatval() após remover os caracteres de agrupamento.
• Arredonda, não trunca. number_format(9.999, 2) retorna "10.00", não "9.99". Para cálculos com moedas, arredonde os valores deliberadamente antes de formatá-los.
• Zero negativo pode aparecer. Números negativos muito pequenos podem ser renderizados como -0.00. Adicione 0 ao valor (ou use abs() em valores próximos de zero) para evitar isso.
• Para moeda com reconhecimento de localidade (símbolos, regras de localidade, formatos contábeis), considere usar o NumberFormatter do PHP, da extensão intl, em vez de construir a string manualmente.

Funções relacionadas

• round() — arredonda um número para uma determinada precisão e retorna um float.
• sprintf() e printf() — formatam números (e outros valores) com marcadores % como %.2f.
• floatval() — converte uma string de volta em um número de ponto flutuante.
• Funções matemáticas do PHP — o conjunto mais amplo de auxiliares numéricos.

Prática