La clase NumberFormatter

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

Introducción

Los programas almacenan y manipulan números utilizando una representación local, binaria e independiente. Al mostrar un número, este se convierte en una versión particular. Por ejemplo, un número como 12345.67 se escribe "12,345.67" en los USA, "12 345,67" en Francia y "12.345,67" en Alemania.

Al llamar a los métodos proporcionados por NumberFormatter, se pueden formatear números, montos de divisas y porcentajes, según las convenciones locales. NumberFormatter tiene en cuenta las convenciones, por lo que debe crearse un nuevo objeto NumberFormatter para cada convención. Las métodos de NumberFormatter formatean tipos primitivos como números decimales, y producen un string.

Para las monedas, se puede utilizar el formato monetario para crear un formateador que devuelve un string, con el símbolo de divisa apropiado. Por supuesto, NumberFormatter no conoce los tipos de cambio, por lo que el formato se realizará, cualquiera sea la divisa solicitada. Esto significa que el mismo número tendrá diferentes valores monetarios según la configuración local. Por ejemplo, el número 9988776.65 se mostrará:

9 988 776,65 € en Francia
9.988.776,65 € en Alemania
$9,988,776.65 en los USA

Para formatear porcentajes, debe crearse un formateador local, con un tipo de formato porcentaje. Con este formateador, una fracción decimal como 0.75 se mostrará como 75%.

Para formatos más complejos, como números escritos literalmente, se utilizan formateadores basados en reglas.

Sinopsis de la clase

class NumberFormatter {

/* Constantes */

public const int PATTERN_DECIMAL;

public const int DECIMAL;

public const int DECIMAL_COMPACT_SHORT;

public const int DECIMAL_COMPACT_LONG;

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_ISO;

public const int CURRENCY_PLURAL;

public const int CURRENCY_ACCOUNTING;

public const int CASH_CURRENCY;

public const int CURRENCY_STANDARD;

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_TOWARD_ZERO;

public const int ROUND_AWAY_FROM_ZERO;

public const int ROUND_HALFEVEN;

public const int ROUND_HALFODD;

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 function __construct(string $locale, int $style, ?string $pattern = null)

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

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

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

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

public function getErrorCode(): int

public function getErrorMessage(): string

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

public function getPattern(): string|false

public function getSymbol(int $symbol): string|false

public function getTextAttribute(int $attribute): string|false

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

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

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

public function setPattern(string $pattern): bool

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

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

}

Constantes predefinidas

Tipos de formato

Estos estilos son utilizados por numfmt_create() para definir el tipo de formateador.

NumberFormatter::PATTERN_DECIMAL int: Formato decimal definido por un patrón
NumberFormatter::DECIMAL int: Formato decimal
NumberFormatter::DECIMAL_COMPACT_SHORT int: Formato decimal expresado en notación compacta (forma corta), p.ej. "23K", "45B". Disponible a partir de PHP 8.5.0 e ICU 56.
NumberFormatter::DECIMAL_COMPACT_LONG int: Formato decimal expresado en notación compacta (forma larga), p.ej. "23 thousand", "45 billion". Disponible a partir de PHP 8.5.0 e ICU 56.
NumberFormatter::CURRENCY int: Formato monetario
NumberFormatter::CURRENCY_ISO int: Formato monetario ISO (p.ej. "USD1.00"). Disponible a partir de PHP 8.5.0.
NumberFormatter::CURRENCY_PLURAL int: Formato monetario plural (p.ej. "1.00 US dollar" y "3.00 US dollars"). Disponible a partir de PHP 8.5.0.
NumberFormatter::CASH_CURRENCY int: Símbolo monetario dado el uso CASH, p.ej. "NT$3" en lugar de "NT$3.23". Disponible a partir de PHP 8.5.0 e ICU 54.
NumberFormatter::CURRENCY_STANDARD int: Símbolo monetario, p.ej. "$1.00", utilizando estilo no contable para valores negativos (p.ej. signo menos). Disponible a partir de PHP 8.5.0 e ICU 56.
NumberFormatter::PERCENT int: Formato porcentual
NumberFormatter::SCIENTIFIC int: Formato científico
NumberFormatter::SPELLOUT int: Formato literal, basado en reglas
NumberFormatter::ORDINAL int: Formato ordinal, basado en reglas
NumberFormatter::DURATION int: Formato de duración, basado en reglas
NumberFormatter::PATTERN_RULEBASED int: Formato de patrón, basado en reglas
NumberFormatter::CURRENCY_ACCOUNTING int: Formato monetario para contabilidad, por ejemplo, ($3.00) para un monto de moneda negativo en lugar de -$3.00. Disponible a partir de PHP 7.4.1 y ICU 53.
NumberFormatter::DEFAULT_STYLE int: Formato por defecto para las convenciones locales
NumberFormatter::IGNORE int: Alias de PATTERN_DECIMAL

Especificadores de formato de número

Estas constantes definen el método de análisis y formato de los números. Deben ser utilizadas como argumentos de las funciones numfmt_format() y numfmt_parse().

NumberFormatter::TYPE_DEFAULT int: Deriva el tipo desde el tipo de variable
NumberFormatter::TYPE_INT32 int: Formatea/analiza un entero de 32 bits
NumberFormatter::TYPE_INT64 int: Formatea/analiza un entero de 64 bits
NumberFormatter::TYPE_DOUBLE int: Formatea/analiza un número decimal
NumberFormatter::TYPE_CURRENCY int: Formatea/analiza un valor monetario. Deprecado a partir de PHP 8.3.0

Atributos de formato de número

Atributos de formatos de número utilizados por numfmt_get_attribute() y numfmt_set_attribute().

NumberFormatter::PARSE_INT_ONLY int: Analiza únicamente los enteros.
NumberFormatter::GROUPING_USED int: Separador de grupos.
NumberFormatter::DECIMAL_ALWAYS_SHOWN int: Muestra siempre una coma decimal.
NumberFormatter::MAX_INTEGER_DIGITS int: Número máximo de dígitos.
NumberFormatter::MIN_INTEGER_DIGITS int: Número mínimo de dígitos.
NumberFormatter::INTEGER_DIGITS int: Número de dígitos.
NumberFormatter::MAX_FRACTION_DIGITS int: Número máximo de decimales.
NumberFormatter::MIN_FRACTION_DIGITS int: Número mínimo de decimales.
NumberFormatter::FRACTION_DIGITS int: Número de decimales.
NumberFormatter::MULTIPLIER int: Multiplicador.
NumberFormatter::GROUPING_SIZE int: Tamaño de agrupamiento.
NumberFormatter::ROUNDING_MODE int: Modo de redondeo.
NumberFormatter::ROUNDING_INCREMENT int: Incremento de redondeo.
NumberFormatter::FORMAT_WIDTH int: El ancho de relleno para el formato de un número.
NumberFormatter::PADDING_POSITION int: La posición en la que se realiza el relleno. Véase las constantes de relleno para tener los diferentes valores posibles.
NumberFormatter::SECONDARY_GROUPING_SIZE int: Tamaño secundario de agrupamiento.
NumberFormatter::SIGNIFICANT_DIGITS_USED int: Utiliza los dígitos significativos.
NumberFormatter::MIN_SIGNIFICANT_DIGITS int: Número mínimo de dígitos significativos.
NumberFormatter::MAX_SIGNIFICANT_DIGITS int: Número máximo de dígitos significativos.
NumberFormatter::LENIENT_PARSE int: Modo de análisis utilizado por los formatos basados en reglas.

Atributos de texto de formato de número

Atributos de texto para los formatos de números, utilizados por numfmt_get_text_attribute() y numfmt_set_text_attribute().

NumberFormatter::POSITIVE_PREFIX int: Prefijo positivo.
NumberFormatter::POSITIVE_SUFFIX int: Sufijo positivo.
NumberFormatter::NEGATIVE_PREFIX int: Prefijo negativo.
NumberFormatter::NEGATIVE_SUFFIX int: Sufijo negativo.
NumberFormatter::PADDING_CHARACTER int: El carácter a utilizar para rellenar los formatos hasta el tamaño.
NumberFormatter::CURRENCY_CODE int: El código de moneda ISO.
NumberFormatter::DEFAULT_RULESET int: El conjunto de reglas por defecto. Solo es utilizable con los formateadores basados en reglas.
NumberFormatter::PUBLIC_RULESETS int: El conjunto de reglas públicas. Esto solo está disponible con los formateadores basados en reglas. Es un atributo de solo lectura. Las reglas públicas se devuelven en forma de una sola cadena, y cada regla está delimitada por un punto y coma ';'.

Especificación de los símbolos de formato

Los símbolos de formato utilizados por numfmt_get_symbol() y numfmt_set_symbol().

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL int: El separador decimal.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL int: El separador de grupos.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL int: El separador de patrón.
NumberFormatter::PERCENT_SYMBOL int: El símbolo de porcentaje.
NumberFormatter::ZERO_DIGIT_SYMBOL int: Cero.
NumberFormatter::DIGIT_SYMBOL int: Un carácter que representa un dígito en un patrón.
NumberFormatter::MINUS_SIGN_SYMBOL int: El signo menos.
NumberFormatter::PLUS_SIGN_SYMBOL int: El signo más.
NumberFormatter::CURRENCY_SYMBOL int: El símbolo de moneda.
NumberFormatter::INTL_CURRENCY_SYMBOL int: El símbolo internacional de moneda.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL int: El separador monetario.
NumberFormatter::EXPONENTIAL_SYMBOL int: El símbolo exponencial.
NumberFormatter::PERMILL_SYMBOL int: El símbolo por mil.
NumberFormatter::PAD_ESCAPE_SYMBOL int: El carácter de escape de símbolos.
NumberFormatter::INFINITY_SYMBOL int: El símbolo de infinito.
NumberFormatter::NAN_SYMBOL int: El símbolo "no es un número".
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL int: El símbolo de dígitos significativos.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL int: El separador de grupos monetarios.

Modos de redondeo

Los modos de redondeo utilizados por las funciones numfmt_get_attribute() y numfmt_set_attribute() con el atributo NumberFormatter::ROUNDING_MODE.

NumberFormatter::ROUND_AWAY_FROM_ZERO: Alias de NumberFormatter::ROUND_UP.
NumberFormatter::ROUND_CEILING: Modo de redondeo hacia el infinito positivo.
NumberFormatter::ROUND_DOWN int: Modo de redondeo hacia cero.
NumberFormatter::ROUND_FLOOR int: Modo de redondeo hacia el infinito negativo.
NumberFormatter::ROUND_HALFDOWN int: Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo inferior en este caso.
NumberFormatter::ROUND_HALFEVEN int: Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo hacia el número par en este caso.
NumberFormatter::ROUND_HALFODD: Modo de redondeo hacia el « vecino impar ».
NumberFormatter::ROUND_HALFUP: Modo de redondeo hacia el entero más cercano, a menos que estén equidistantes: redondeo superior en este caso.
NumberFormatter::ROUND_TOWARD_ZERO: Alias de NumberFormatter::ROUND_DOWN.
NumberFormatter::ROUND_UP int: Modo de redondeo que aleja de cero.

Especificadores de relleno

Valores de relleno utilizados por numfmt_get_attribute() y numfmt_set_attribute() con el atributo NumberFormatter::PADDING_POSITION.

NumberFormatter::PAD_AFTER_PREFIX int: Caracteres de relleno añadidos después del prefijo.
NumberFormatter::PAD_AFTER_SUFFIX int: Caracteres de relleno añadidos después del sufijo.
NumberFormatter::PAD_BEFORE_PREFIX int: Caracteres de relleno añadidos antes del prefijo.
NumberFormatter::PAD_BEFORE_SUFFIX int: Caracteres de relleno añadidos antes del sufijo.

Véase también

Historial de cambios

Versión	Descripción
8.5.0	Se añadieron `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0	Las constantes de clase ahora están tipadas.

Tabla de contenidos

NumberFormatter::create — Crea un formateador de números
NumberFormatter::format — Formatear un número
NumberFormatter::formatCurrency — Formatea un valor monetario
NumberFormatter::getAttribute — Lee un atributo
NumberFormatter::getErrorCode — Obtener el último código de error del formateador
NumberFormatter::getErrorMessage — Lee el último mensaje de error del formateador
NumberFormatter::getLocale — Lee la configuración local del formateador
NumberFormatter::getPattern — Lee el modelo del formateador
NumberFormatter::getSymbol — Lee el valor del símbolo
NumberFormatter::getTextAttribute — Lee un atributo textual
NumberFormatter::parse — Analiza un número
NumberFormatter::parseCurrency — Analiza un número monetario
NumberFormatter::setAttribute — Asigna un atributo al formateador
NumberFormatter::setPattern — Configura el patrón del formateador
NumberFormatter::setSymbol — Configura el símbolo del formateador
NumberFormatter::setTextAttribute — Modifica un atributo de texto

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 5 notes

down

giorgio dot liscio at email dot it ¶

15 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

jimbo2150 at gmail dot com ¶

3 years 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

stan at dragnev dot ca ¶

5 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

sudheer at binaryvibes dot co dot in ¶

15 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

Einenlum ¶

2 years 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);

＋add a note