PHP Reference ยท Standard PHP Library and Classes
The NumberFormatter class
Reference for PHP NumberFormatter (intl): format decimals, currencies, percentages and spelled-out numbers per locale, parse strings and set digits and rounding.
NumberFormatter (from the intl extension) writes numbers the way people in a given locale expect them: 1,234.5 in the United States, 1.234,5 in Germany, 1 234,5 in France. It also formats currencies, percentages, scientific notation, spelled-out words ("one thousand") and ordinals ("3rd"), and parses such strings back into numbers.
It needs the intl extension, which this site's runner lacks, so the formatting examples below are read-only and the live examples show how to guard and fall back.
$f = new NumberFormatter('en_US', NumberFormatter::CURRENCY); echo $f->formatCurrency(1234.5, 'USD'); // $1,234.50
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
new NumberFormatter(string $locale, int $style, ?string $pattern = null) NumberFormatter::format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false NumberFormatter::formatCurrency(float $amount, string $currency): string|false NumberFormatter::parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, &$offset = null): int|float|false NumberFormatter::setAttribute(int $attribute, int|float $value): bool
| Name | Description |
|---|---|
$locale |
Locale ID such as en_US, de_DE, fr_FR, ja_JP. |
$style |
DECIMAL, CURRENCY, PERCENT, SCIENTIFIC, SPELLOUT, ORDINAL, DURATION, PATTERN_DECIMAL, CURRENCY_ACCOUNTING and others. |
$pattern |
ICU pattern, only with PATTERN_DECIMAL (for example #,##0.00). |
$type |
For format(): TYPE_INT32, TYPE_INT64, TYPE_DOUBLE; the default picks one from the value. |
$currency |
ISO 4217 code such as EUR. |
Return value: a formatted string, or false on failure.
Read-only examples
$value = 1234567.891; (new NumberFormatter('en_US', NumberFormatter::DECIMAL))->format($value); // 1,234,567.891 (new NumberFormatter('de_DE', NumberFormatter::DECIMAL))->format($value); // 1.234.567,891 (new NumberFormatter('en_US', NumberFormatter::PERCENT))->format(0.256); // 26% (new NumberFormatter('en_US', NumberFormatter::SPELLOUT))->format(1234); // one thousand two hundred thirty-four (new NumberFormatter('en_US', NumberFormatter::ORDINAL))->format(3); // 3rd $f = new NumberFormatter('en_US', NumberFormatter::DECIMAL); $f->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 1); echo $f->format(2.46); // 2.5 $parser = new NumberFormatter('de_DE', NumberFormatter::DECIMAL); var_dump($parser->parse('1.234,5')); // float(1234.5)
Usage notes
- Check for the extension.
new NumberFormatterthrowsError(class not found) withoutintl. - Format only for display. Keep calculations in
intcents or a decimal library, never in strings produced for people. - Whitespace is not always a plain space. German currency output and French grouping use non-breaking spaces; normalize them before comparing.
formatCurrency()uses the currency's default digits (two for USD, zero for JPY) unless you changeMIN_FRACTION_DIGITSandMAX_FRACTION_DIGITS.- Rounding mode defaults to half-even; set
NumberFormatter::ROUNDING_MODEwithROUND_HALFUPand friends for the result schools and invoices expect. parse()is locale-bound. A German formatter reads1.234,5as 1234.5; an English one stops at the comma. Afalseresult means nothing could be parsed.- Errors: after a failure,
getErrorCode()andgetErrorMessage()tell why. - Without intl,
number_format()can mimic a locale only if you pass its separators yourself; see its page.
Related
Intl classes,number_format(),round()- Lessons: Numbers, String formatting