A classe NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Introdução

Programas armazenam e operam números usando uma representação binária que não depende da localidade. Ao apresentar ou imprimir um número, ele é convertido para uma string específica para a localidade. Por exemplo, o número 12345.67 é "12,345.67" nos Estados Unidos, "12 345,67" na França e "12.345,67" na Alemanha e no Brasil.

Ao invocar os métodos fornecidos pela classe NumberFormatter, pode-se formatar números, moedas, e percentagens de acordo com o especificado ou com a localidade padrão. NumberFormatter é sensível à localidade, portanto é necessário criar um novo objeto NumberFormatter para cada localidade. Métodos NumberFormatter formatam números com tipos primitivos, como 'double' e mostram o número como uma string específica para a localidade

Para moedas, pode-se usar o tipo de formato de moeda para criar um formatador que retorne uma string com o número formatado e com o sinal apropriado para a moeda. Obviamente, a classe NumberFormatter não tem ciência de taxas de câmbio, portanto, a saída é a mesma independente da moeda especificada. Isto significa que o mesmo número tem diferentes valores monteários dependendo da moeda da localidade. Se o número for 9988776.65, os resultados serão:

9 988 776,65 € na França
9.988.776,65 € na Alemanha
$9,988,776.65 nos Estados Unidos

Para formatar percentagens, deve-se criar um formatador específico da localidade com o tipo de formato de percentual. Com este formatados, uma fração decimal como 0.75 é mostrada como 75%.

Para formatações mais complexas, como números por extenso, os formatadores de número baseados em regras são utilizados.

Resumo da classe

class NumberFormatter {

/* Constantes */

public const int PATTERN_DECIMAL;

public const int DECIMAL;

public const int CURRENCY;

public const int PERCENT;

public const int SCIENTIFIC;

public const int SPELLOUT;

public const int ORDINAL;

public const int DURATION;

public const int PATTERN_RULEBASED;

public const int IGNORE;

public const int CURRENCY_ACCOUNTING;

public const int DEFAULT_STYLE;

public const int ROUND_CEILING;

public const int ROUND_FLOOR;

public const int ROUND_DOWN;

public const int ROUND_UP;

public const int ROUND_HALFEVEN;

public const int ROUND_HALFDOWN;

public const int ROUND_HALFUP;

public const int PAD_BEFORE_PREFIX;

public const int PAD_AFTER_PREFIX;

public const int PAD_BEFORE_SUFFIX;

public const int PAD_AFTER_SUFFIX;

public const int PARSE_INT_ONLY;

public const int GROUPING_USED;

public const int DECIMAL_ALWAYS_SHOWN;

public const int MAX_INTEGER_DIGITS;

public const int MIN_INTEGER_DIGITS;

public const int INTEGER_DIGITS;

public const int MAX_FRACTION_DIGITS;

public const int MIN_FRACTION_DIGITS;

public const int FRACTION_DIGITS;

public const int MULTIPLIER;

public const int GROUPING_SIZE;

public const int ROUNDING_MODE;

public const int ROUNDING_INCREMENT;

public const int FORMAT_WIDTH;

public const int PADDING_POSITION;

public const int SECONDARY_GROUPING_SIZE;

public const int SIGNIFICANT_DIGITS_USED;

public const int MIN_SIGNIFICANT_DIGITS;

public const int MAX_SIGNIFICANT_DIGITS;

public const int LENIENT_PARSE;

public const int POSITIVE_PREFIX;

public const int POSITIVE_SUFFIX;

public const int NEGATIVE_PREFIX;

public const int NEGATIVE_SUFFIX;

public const int PADDING_CHARACTER;

public const int CURRENCY_CODE;

public const int DEFAULT_RULESET;

public const int PUBLIC_RULESETS;

public const int DECIMAL_SEPARATOR_SYMBOL;

public const int GROUPING_SEPARATOR_SYMBOL;

public const int PATTERN_SEPARATOR_SYMBOL;

public const int PERCENT_SYMBOL;

public const int ZERO_DIGIT_SYMBOL;

public const int DIGIT_SYMBOL;

public const int MINUS_SIGN_SYMBOL;

public const int PLUS_SIGN_SYMBOL;

public const int CURRENCY_SYMBOL;

public const int INTL_CURRENCY_SYMBOL;

public const int MONETARY_SEPARATOR_SYMBOL;

public const int EXPONENTIAL_SYMBOL;

public const int PERMILL_SYMBOL;

public const int PAD_ESCAPE_SYMBOL;

public const int INFINITY_SYMBOL;

public const int NAN_SYMBOL;

public const int SIGNIFICANT_DIGIT_SYMBOL;

public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;

public const int TYPE_DEFAULT;

public const int TYPE_INT32;

public const int TYPE_INT64;

public const int TYPE_DOUBLE;

public const int TYPE_CURRENCY;

/* Métodos */

public __construct(string $locale, int $style, ?string $pattern = null)

public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter

public formatCurrency(float $amount, string $currency): string|false

public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false

public getAttribute(int $attribute): int|float|false

public getErrorCode(): int

public getErrorMessage(): string

public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false

public getPattern(): string|false

public getSymbol(int $symbol): string|false

public getTextAttribute(int $attribute): string|false

public parseCurrency(string $string, string &$currency, int &$offset = null): float|false

public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false

public setAttribute(int $attribute, int|float $value): bool

public setPattern(string $pattern): bool

public setSymbol(int $symbol, string $value): bool

public setTextAttribute(int $attribute, string $value): bool

}

Constantes pré-definidas

Estes estilos são usados pela função numfmt_create() para definir o tipo do formatador.

NumberFormatter::PATTERN_DECIMAL: Formato decimal definido por modelo
NumberFormatter::DECIMAL: Formato decimal
NumberFormatter::CURRENCY: Formato de moeda
NumberFormatter::PERCENT: Formato de percentual
NumberFormatter::SCIENTIFIC: Formato científico
NumberFormatter::SPELLOUT: Formato baseado em regras ortográficas
NumberFormatter::ORDINAL: Formato baseado em regras ordinais
NumberFormatter::DURATION: Formato baseado em regras de duração
NumberFormatter::PATTERN_RULEBASED: Formato baseado em regras definido por modelo
NumberFormatter::CURRENCY_ACCOUNTING: Formato de moeda para contabilidade, ex.: ($3.00) para quantidade negativa de moeda ao invés de -$3.00. Disponível a partir do PHP 7.4.1 e ICU 53.
NumberFormatter::DEFAULT_STYLE: Formato padrão para a localidade
NumberFormatter::IGNORE: Apelido para PATTERN_DECIMAL

Estas constantes definem como os números são analisados ou formatados. Eles devem ser usados como argumentos para as funções numfmt_format() e numfmt_parse().

NumberFormatter::TYPE_DEFAULT: Deriva o tipo a partir do tipo da variável
NumberFormatter::TYPE_INT32: Formata/analisa como um inteiro de 32 bits
NumberFormatter::TYPE_INT64: Formata/analisa como um inteiro de 64 bits
NumberFormatter::TYPE_DOUBLE: Formata/analisa como um valor de ponto flutuante
NumberFormatter::TYPE_CURRENCY: Formata/analisa como um valor de moeda. Defasado a partir do PHP 8.3.0

Atributo de formato de número usado pelas funções numfmt_get_attribute() e numfmt_set_attribute().

NumberFormatter::PARSE_INT_ONLY: Analisa inteiros somente.
NumberFormatter::GROUPING_USED: Usa separador de agrupamento.
NumberFormatter::DECIMAL_ALWAYS_SHOWN: Sempre mostra o separador de decimais.
NumberFormatter::MAX_INTEGER_DIGITS: Máximo de dígitos inteiros.
NumberFormatter::MIN_INTEGER_DIGITS: Mínimo de dígitos inteiros.
NumberFormatter::INTEGER_DIGITS: Dígitos inteiros.
NumberFormatter::MAX_FRACTION_DIGITS: Máximo de dígitos decimais.
NumberFormatter::MIN_FRACTION_DIGITS: Mínimo de dígitos decimais.
NumberFormatter::FRACTION_DIGITS: Dígitos decimais.
NumberFormatter::MULTIPLIER: Multiplicador.
NumberFormatter::GROUPING_SIZE: Tamanho do agrupamento.
NumberFormatter::ROUNDING_MODE: Modo de arredondamento.
NumberFormatter::ROUNDING_INCREMENT: Incremento de arredondamento.
NumberFormatter::FORMAT_WIDTH: A largura para a qual a saída de format() será preenchida.
NumberFormatter::PADDING_POSITION: A posição na qual o preenchimento acontecerá. Consulte as constantes de posição de preenchimento para possíveis valores de argumentos.
NumberFormatter::SECONDARY_GROUPING_SIZE: Tamanho de agrupamento secundário.
NumberFormatter::SIGNIFICANT_DIGITS_USED: Usa dígitos significativos.
NumberFormatter::MIN_SIGNIFICANT_DIGITS: Mínimo de dígitos significativos.
NumberFormatter::MAX_SIGNIFICANT_DIGITS: Máximo de dígitos significativos.
NumberFormatter::LENIENT_PARSE: Modo de análise brando usado por formatos baseados em regras.

Atributo de texto de formato numérico usado por numfmt_get_text_attribute() e numfmt_set_text_attribute().

NumberFormatter::POSITIVE_PREFIX: Prefixo positivo.
NumberFormatter::POSITIVE_SUFFIX: Sufixo positivo.
NumberFormatter::NEGATIVE_PREFIX: Prefixo negativo.
NumberFormatter::NEGATIVE_SUFFIX: Sufixo negativo.
NumberFormatter::PADDING_CHARACTER: O caractere usado para preencher a largura do formato.
NumberFormatter::CURRENCY_CODE: O código de moeda ISO.
NumberFormatter::DEFAULT_RULESET: O conjunto de regras padrão. Isso está disponível apenas com formatadores baseados em regras.
NumberFormatter::PUBLIC_RULESETS: Os conjuntos de regras públicas. Isso está disponível apenas com formatadores baseados em regras. Este é um atributo somente leitura. Os conjuntos de regras públicos são retornados como uma única string, com cada nome de conjunto de regras delimitado por ';' (ponto e vírgula).

Símbolos de formato de número usados por numfmt_get_symbol() e numfmt_set_symbol().

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL: O separador de decimais.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL: O separador de agrupamento.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL: O separador de padrão.
NumberFormatter::PERCENT_SYMBOL: O sinal de percentagem.
NumberFormatter::ZERO_DIGIT_SYMBOL: Zero.
NumberFormatter::DIGIT_SYMBOL: Caractere representando um dígito no padrão.
NumberFormatter::MINUS_SIGN_SYMBOL: O sinal de menos.
NumberFormatter::PLUS_SIGN_SYMBOL: O sinal de mais.
NumberFormatter::CURRENCY_SYMBOL: O símbolo da moeda.
NumberFormatter::INTL_CURRENCY_SYMBOL: O símbolo internacional da moeda.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL: O separador monetário.
NumberFormatter::EXPONENTIAL_SYMBOL: O símbolo exponencial.
NumberFormatter::PERMILL_SYMBOL: O símbolo de permilagem.
NumberFormatter::PAD_ESCAPE_SYMBOL: Caractere de preenchimento de escape.
NumberFormatter::INFINITY_SYMBOL: Símbolo de infinito.
NumberFormatter::NAN_SYMBOL: Símbolo representando que o valor não é um número.
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL: Símbolo de dígito significativo.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL: O separador de agrupamento monetário.

Valores de modo de arredondamento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo NumberFormatter::ROUNDING_MODE.

NumberFormatter::ROUND_CEILING: Modo de arredondamento para arredondar em direção ao infinito positivo.
NumberFormatter::ROUND_DOWN: Modo de arredondamento para arredondar para zero.
NumberFormatter::ROUND_FLOOR: Modo de arredondamento para arredondar em direção ao infinito negativo.
NumberFormatter::ROUND_HALFDOWN: Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes, caso em que arredonda para baixo.
NumberFormatter::ROUND_HALFEVEN: Modo de arredondamento para arredondar em direção ao "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar em direção ao vizinho par.
NumberFormatter::ROUND_HALFUP: Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar para cima.
NumberFormatter::ROUND_UP: Modo de arredondamento para arredondar a partir de zero.

Valores de posição de preenchimento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo NumberFormatter::PADDING_POSITION.

NumberFormatter::PAD_AFTER_PREFIX: Caracteres de preenchimento inseridos após o prefixo.
NumberFormatter::PAD_AFTER_SUFFIX: Caracteres de preenchimento inseridos após o sufixo.
NumberFormatter::PAD_BEFORE_PREFIX: Caracteres de preenchimento inseridos antes do prefixo.
NumberFormatter::PAD_BEFORE_SUFFIX: Caracteres de preenchimento inseridos antes do sufixo.

Veja Também

Índice

NumberFormatter::create — Cria um formatador de número
NumberFormatter::formatCurrency — Formata um valor de moeda
NumberFormatter::format — Formata um número
NumberFormatter::getAttribute — Obtém um atributo
NumberFormatter::getErrorCode — Obtém o último código de erro do formatador
NumberFormatter::getErrorMessage — Obtém a última mensagem de erro do formatador
NumberFormatter::getLocale — Obtém a localidade do formatador
NumberFormatter::getPattern — Obtém padrão do formatador
NumberFormatter::getSymbol — Obtém um valor de símbolo
NumberFormatter::getTextAttribute — Obtém um atributo de texto
NumberFormatter::parseCurrency — Interpreta um valor monetário
NumberFormatter::parse — Interpreta um número
NumberFormatter::setAttribute — Define um atributo
NumberFormatter::setPattern — Define o padrão do formatador
NumberFormatter::setSymbol — Define um valor de símbolo
NumberFormatter::setTextAttribute — Define um atributo de texto

add a note

User Contributed Notes 9 notes

down

giorgio dot liscio at email dot it ¶

13 years ago


this class seems to be painful: it is not, formatting and parsing are highly customizable, but what you probably need is really simple:



if you want to localize a number use:



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::DECIMAL);

echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12

$a->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, 0);

$a->setAttribute(\NumberFormatter::MAX_FRACTION_DIGITS, 100); // by default some locales got max 2 fraction digits, that is probably not what you want

echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12345

?>



if you want to print money use:



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

echo $a->format(12345.12345) . "<br>"; // outputs €12.345,12

?>



if you have money data stored as (for example) US dollars and you want to print them using the it-IT notation, you need to use



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

echo $a->formatCurrency(12345, "USD") . "<br>"; // outputs $ 12.345,00 and it is formatted using the italian notation (comma as decimal separator)

?>



another useful example about currency (how to obtain the currency name by a locale string):



<?php

$frontEndFormatter = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

$adminFormatter = new \NumberFormatter("en-US", \NumberFormatter::CURRENCY);

$symbol = $adminFormatter->getSymbol(\NumberFormatter::INTL_CURRENCY_SYMBOL); // got USD

echo $frontEndFormatter->formatCurrency(12345.12345,  $symbol) . "<br>";

?>

down

stan at dragnev dot ca ¶

4 years ago


Here's an example of how to use PATTERN_DECIMAL to print a number with two fraction digits, use () for negative numbers and pad to five characters to the left of the decimal point, using spaces as the padding character:

<?php

$fmt = new NumberFormatter("en-CA", NumberFormatter::PATTERN_DECIMAL, "* #####.00 ;(* #####.00)");
echo $fmt->format(-45.1);

// Outputs: "  (45.10)"

?>

Note that the ; in the pattern denotes the beginning of a subpattern, which is used for negative numbers. Hence the brackets around the pattern after the semicolon.

down

Einenlum ¶

10 months ago


Be aware that (at least with the locale 'fr-FR') NumberFormatter doesn't use spaces. It doesn't even use non breakable spaces (NBSP). It uses narrow non breakable spaces (NNBSP). This broke my tests.

<?php

$formatter = new NumberFormatter(
    'fr-FR',
    NumberFormatter::DEFAULT_STYLE
);

$value = $formatter->format(100_000); // '100 000'

// If you want to replace narrow non breakable spaces with non breakable spaces:

str_replace("\u{202F}", "\u{00A0}", $value);

// If you want to replace it with a normal space

str_replace("\u{202F}", " ", $value);

down

gwyneth dot llewelyn at gwynethllewelyn dot net ¶

2 years ago


When using the `NumberFormatter` class for pretty-printing currency in PHP 7.3 and 8+, it's not clear from the documentation that you can use the empty string "" as the locale for the constructor, and that will retrieve the default locale (whatever it has been set to in your environment).

`formatCurrency()`, by contrast, does not accept the empty string for the default currency symbol; it will display a 'generic' currency symbol instead (¤).

Tested with PHP 7.4.30, 8.0.21, 8.1.8 under Ubuntu Linux and 8.1.8 under macOS Big Sur (11.6.8). I tried under other alternatives (e.g. Linux running on ARM chips, PHP 7.3.3) but sadly the `NumberFormatter` library does not seem to be present (or could not be found) on those systems...

down

sudheer at binaryvibes dot co dot in ¶

13 years ago


Sample script to print number in English.

<?php
$f = new NumberFormatter("en", NumberFormatter::SPELLOUT);
echo $f->format(123456);

?>

Produces the result:
one hundred twenty-three thousand four hundred fifty-six

down

-2

AF ¶

4 years ago


Please pay attention to the Arabic decimal separator (https://en.wikipedia.org/wiki/Decimal_separator#Other_numeral_systems).

All the following conditions are true:
<?php
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) === '٫';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) == '٫';

(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) !== ',';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) != ',';
?>

down

-3

Joey ¶

7 years ago


Be warned that this class sometimes lacks sufficient error output. I recently instantiated it while invalid pattern to the constructor.

    php -r '$nf = new \NumberFormatter("tlh-KX.UTF8", \NumberFormatter::IGNORE, "{,,#;#}");var_dump($nf->format(5));'

    Fatal error: Call to a member function format() on null in Command line code on line 1

Rather than emitting an error message or throwing an exception null is returned after calling new.

I'm not sure if it's fixed in PHP 7 but it's something to watch out for. Make sure you check your parameters very closely.

down

-1

jimbo2150 at gmail dot com ¶

1 year ago


The NumberFormatter class can be used to convert integer numbers to Roman numerals without a custom function using an array of symbols and associated values:

<?php

function intToRomanNumeral(int $num) {
    static $nf = new NumberFormatter('@numbers=roman', NumberFormatter::DECIMAL);
    return $nf->format($num);
}

echo intToRomanNumeral(2); // II

echo intToRomanNumeral(5); // V

echo intToRomanNumeral(10); // X

echo intToRomanNumeral(50); // L

echo intToRomanNumeral(57); // LVII
echo intToRomanNumeral(58); // LVIII

echo intToRomanNumeral(100); // C

echo intToRomanNumeral(150); // CL

echo intToRomanNumeral(1000); // M

echo intToRomanNumeral(10000); // ↂ

?>

down

-11

Adam ¶

7 years ago


Good to know Numberformatter::SPELLOUT using soft hypens.

So, if you want to avoid it use preg_replace:

<?php
$azaz = new NumberFormatter("hu-HU", NumberFormatter::SPELLOUT);
$text = preg_replace('~\x{00AD}~u', '', $azaz->format(123456));
print $text;
?>
Output without preg_replace:
egy-száz-huszon-három-ezer négy-száz-ötven-hat

Output with preg_replace:
egyszázhuszonháromezer négyszázötvenhat

add a note