The NumberFormatter class

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

Introduction

Programs store and operate on numbers using a locale-independent binary representation. When displaying or printing a number it is converted to a locale-specific string. For example, the number 12345.67 is "12,345.67" in the US, "12 345,67" in France and "12.345,67" in Germany.

By invoking the methods provided by the NumberFormatter class, you can format numbers, currencies, and percentages according to the specified or default locale. NumberFormatter is locale-sensitive so you need to create a new NumberFormatter for each locale. NumberFormatter methods format primitive-type numbers, such as double and output the number as a locale-specific string.

For currencies you can use currency format type to create a formatter that returns a string with the formatted number and the appropriate currency sign. Of course, the NumberFormatter class is unaware of exchange rates so, the number output is the same regardless of the specified currency. This means that the same number has different monetary values depending on the currency locale. If the number is 9988776.65 the results will be:

9 988 776,65 € in France
9.988.776,65 € in Germany
$9,988,776.65 in the United States

In order to format percentages, create a locale-specific formatter with percentage format type. With this formatter, a decimal fraction such as 0.75 is displayed as 75%.

For more complex formatting, like spelled-out numbers, the rule-based number formatters are used.

Class synopsis

class NumberFormatter {

/* Constants */

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

/* Methods */

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

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

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

public formatCurrency(float $amount, string $currency): 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 parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false

public parseCurrency(string $string, string &$currency, int &$offset = null): 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

}

Predefined Constants

Format Types

These styles are used by the numfmt_create() to define the type of the formatter.

NumberFormatter::PATTERN_DECIMAL int: Decimal format defined by pattern
NumberFormatter::DECIMAL int: Decimal format
NumberFormatter::CURRENCY int: Currency format
NumberFormatter::PERCENT int: Percent format
NumberFormatter::SCIENTIFIC int: Scientific format
NumberFormatter::SPELLOUT int: Spellout rule-based format
NumberFormatter::ORDINAL int: Ordinal rule-based format
NumberFormatter::DURATION int: Duration rule-based format
NumberFormatter::PATTERN_RULEBASED int: Rule-based format defined by pattern
NumberFormatter::CURRENCY_ACCOUNTING int: Currency format for accounting, e.g., ($3.00) for negative currency amount instead of -$3.00. Available as of PHP 7.4.1 and ICU 53.
NumberFormatter::DEFAULT_STYLE int: Default format for the locale
NumberFormatter::IGNORE int: Alias for PATTERN_DECIMAL

Number Format Specifiers

These constants define how the numbers are parsed or formatted. They should be used as arguments to numfmt_format() and numfmt_parse().

NumberFormatter::TYPE_DEFAULT int: Derive the type from variable type
NumberFormatter::TYPE_INT32 int: Format/parse as 32-bit integer
NumberFormatter::TYPE_INT64 int: Format/parse as 64-bit integer
NumberFormatter::TYPE_DOUBLE int: Format/parse as floating point value
NumberFormatter::TYPE_CURRENCY int: Format/parse as currency value. Deprecated as of PHP 8.3.0

Number Format Attributes

Number format attribute used by numfmt_get_attribute() and numfmt_set_attribute().

NumberFormatter::PARSE_INT_ONLY int: Parse integers only.
NumberFormatter::GROUPING_USED int: Use grouping separator.
NumberFormatter::DECIMAL_ALWAYS_SHOWN int: Always show decimal point.
NumberFormatter::MAX_INTEGER_DIGITS int: Maximum integer digits.
NumberFormatter::MIN_INTEGER_DIGITS int: Minimum integer digits.
NumberFormatter::INTEGER_DIGITS int: Integer digits.
NumberFormatter::MAX_FRACTION_DIGITS int: Maximum fraction digits.
NumberFormatter::MIN_FRACTION_DIGITS int: Minimum fraction digits.
NumberFormatter::FRACTION_DIGITS int: Fraction digits.
NumberFormatter::MULTIPLIER int: Multiplier.
NumberFormatter::GROUPING_SIZE int: Grouping size.
NumberFormatter::ROUNDING_MODE int: Rounding Mode.
NumberFormatter::ROUNDING_INCREMENT int: Rounding increment.
NumberFormatter::FORMAT_WIDTH int: The width to which the output of format() is padded.
NumberFormatter::PADDING_POSITION int: The position at which padding will take place. See pad position constants for possible argument values.
NumberFormatter::SECONDARY_GROUPING_SIZE int: Secondary grouping size.
NumberFormatter::SIGNIFICANT_DIGITS_USED int: Use significant digits.
NumberFormatter::MIN_SIGNIFICANT_DIGITS int: Minimum significant digits.
NumberFormatter::MAX_SIGNIFICANT_DIGITS int: Maximum significant digits.
NumberFormatter::LENIENT_PARSE int: Lenient parse mode used by rule-based formats.

Number Format Text Attributes

Number format text attribute used by numfmt_get_text_attribute() and numfmt_set_text_attribute().

NumberFormatter::POSITIVE_PREFIX int: Positive prefix.
NumberFormatter::POSITIVE_SUFFIX int: Positive suffix.
NumberFormatter::NEGATIVE_PREFIX int: Negative prefix.
NumberFormatter::NEGATIVE_SUFFIX int: Negative suffix.
NumberFormatter::PADDING_CHARACTER int: The character used to pad to the format width.
NumberFormatter::CURRENCY_CODE int: The ISO currency code.
NumberFormatter::DEFAULT_RULESET int: The default rule set. This is only available with rule-based formatters.
NumberFormatter::PUBLIC_RULESETS int: The public rule sets. This is only available with rule-based formatters. This is a read-only attribute. The public rulesets are returned as a single string, with each ruleset name delimited by ';' (semicolon).

Symbol Format Specifiers

Number format symbols used by numfmt_get_symbol() and numfmt_set_symbol().

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL int: The decimal separator.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL int: The grouping separator.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL int: The pattern separator.
NumberFormatter::PERCENT_SYMBOL int: The percent sign.
NumberFormatter::ZERO_DIGIT_SYMBOL int: Zero.
NumberFormatter::DIGIT_SYMBOL int: Character representing a digit in the pattern.
NumberFormatter::MINUS_SIGN_SYMBOL int: The minus sign.
NumberFormatter::PLUS_SIGN_SYMBOL int: The plus sign.
NumberFormatter::CURRENCY_SYMBOL int: The currency symbol.
NumberFormatter::INTL_CURRENCY_SYMBOL int: The international currency symbol.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL int: The monetary separator.
NumberFormatter::EXPONENTIAL_SYMBOL int: The exponential symbol.
NumberFormatter::PERMILL_SYMBOL int: Per mill symbol.
NumberFormatter::PAD_ESCAPE_SYMBOL int: Escape padding character.
NumberFormatter::INFINITY_SYMBOL int: Infinity symbol.
NumberFormatter::NAN_SYMBOL int: Not-a-number symbol.
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL int: Significant digit symbol.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL int: The monetary grouping separator.

Rounding Modes

Rounding mode values used by numfmt_get_attribute() and numfmt_set_attribute() with NumberFormatter::ROUNDING_MODE attribute.

NumberFormatter::ROUND_AWAY_FROM_ZERO: Alias of NumberFormatter::ROUND_UP.
NumberFormatter::ROUND_CEILING int: Rounding mode to round towards positive infinity.
NumberFormatter::ROUND_DOWN int: Rounding mode to round towards zero.
NumberFormatter::ROUND_FLOOR int: Rounding mode to round towards negative infinity.
NumberFormatter::ROUND_HALFDOWN int: Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
NumberFormatter::ROUND_HALFEVEN int: Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
NumberFormatter::ROUND_HALFODD: Rounding mode to round towards the "odd neighbor".
NumberFormatter::ROUND_HALFUP int: Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
NumberFormatter::ROUND_TOWARD_ZERO: Alias of NumberFormatter::ROUND_DOWN.
NumberFormatter::ROUND_UP int: Rounding mode to round away from zero.

Padding Specifiers

Pad position values used by numfmt_get_attribute() and numfmt_set_attribute() with NumberFormatter::PADDING_POSITION attribute.

NumberFormatter::PAD_AFTER_PREFIX int: Pad characters inserted after the prefix.
NumberFormatter::PAD_AFTER_SUFFIX int: Pad characters inserted after the suffix.
NumberFormatter::PAD_BEFORE_PREFIX int: Pad characters inserted before the prefix.
NumberFormatter::PAD_BEFORE_SUFFIX int: Pad characters inserted before the suffix.

Changelog

Version	Description
8.4.0	The class constants are now typed.

NumberFormatter::create — Create a number formatter
NumberFormatter::format — Format a number
NumberFormatter::formatCurrency — Format a currency value
NumberFormatter::getAttribute — Get an attribute
NumberFormatter::getErrorCode — Get formatter's last error code
NumberFormatter::getErrorMessage — Get formatter's last error message
NumberFormatter::getLocale — Get formatter locale
NumberFormatter::getPattern — Get formatter pattern
NumberFormatter::getSymbol — Get a symbol value
NumberFormatter::getTextAttribute — Get a text attribute
NumberFormatter::parse — Parse a number
NumberFormatter::parseCurrency — Parse a currency number
NumberFormatter::setAttribute — Set an attribute
NumberFormatter::setPattern — Set formatter pattern
NumberFormatter::setSymbol — Set a symbol value
NumberFormatter::setTextAttribute — Set a text attribute

Found A Problem?

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

＋add a note

User Contributed Notes 8 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

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

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

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

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

-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.

＋add a note

The NumberFormatter class

Introduction

Class synopsis

Predefined Constants

Format Types

Number Format Specifiers

Number Format Attributes

Number Format Text Attributes

Symbol Format Specifiers

Rounding Modes

Padding Specifiers

See Also

Changelog

Table of Contents

Found A Problem?

User Contributed Notes 8 notes