array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.number-format.php', 1 => 'number_format', 2 => 'Formata um número com milhares agrupados', ), 'up' => array ( 0 => 'ref.strings.php', 1 => 'Funções de String', ), 'prev' => array ( 0 => 'function.nl2br.php', 1 => 'nl2br', ), 'next' => array ( 0 => 'function.ord.php', 1 => 'ord', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/strings/functions/number-format.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

number_format

(PHP 4, PHP 5, PHP 7, PHP 8)

number_format — Formata um número com milhares agrupados

Descrição

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

Formata um número com milhares agrupados e opcionalmente dígitos decimais usando a regra de arredondamento de meia unidade para cima.

Parâmetros

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.

Valor Retornado

Uma versão formatada de num.

Registro de Alterações

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.

Exemplos

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"

Veja Também