(PHP 4, PHP 5, PHP 7, PHP 8)
number_format — Formata um número com milhares agrupados
$num
,$decimals
= 0,$decimal_separator
= ".",$thousands_separator
= ","Formata um número com milhares agrupados e opcionalmente dígitos decimais usando a regra de arredondamento de meia unidade para cima.
num
O número a ser formatado.
decimals
Define o número de dígitos decimais.
Se for igual a 0
, o separador de decimais definido por decimal_separator
é
omitido do valor de retorno.
A partir do PHP 8.3.0, quando o valor é negativo, num
é arredondado para o número de dígitos significativos informado em decimals
antes
do separador de decimais.
Antes do PHP 8.3.0, valores negativos eram ignorados e manipulados como
se fossem 0
.
decimal_separator
Define a string separadora de decimais.
thousands_separator
Define a string separadora de milhares.
Uma versão formatada de num
.
Versão | Descrição |
---|---|
8.3.0 |
Adicionada a manipulação de valores negativos para decimals .
|
8.0.0 | Antes desta versão, number_format() aceitava um, dois ou quatro parâmetros (mas não três). |
7.2.0 |
number_format() foi modificado para não ser capaz de retornar
-0 , anteriormente -0 poderia ser retornado
para casos onde num fosse -0.01 .
|
Exemplo #1 Exemplo de number_format()
Por exemplo, a notação francesa normalmente usa duas casas decimais, vírgula (',') como separador de decimais e espaço (' ') como separador de milhares. O exemplo a seguir demonstra várias formas de formatar um número:
<?php
$number = 1234.56;
// notação inglesa (padrão)
echo number_format($number), PHP_EOL;
// 1,235
// notação francesa
echo number_format($number, 2, ',', ' '), PHP_EOL;
// 1 234,56
$number = 1234.5678;
// notação inglesa sem separador de milhares
echo number_format($number, 2, '.', ''), PHP_EOL;
// 1234.57
?>
Exemplo #2 Um valor negativo para decimals
A partir do PHP 8.3.0, um valor negativo para decimals
é usado para arredondar o número de dígitos significativos antes do separador
de decimais.
<?php
$number = "1234.5678";
var_dump(number_format($number, -1));
var_dump(number_format($number, -2));
var_dump(number_format($number, -3));
?>
O exemplo acima produzirá:
string(5) "1,230" string(5) "1,200" string(5) "1,000"