Skip to content
Tutorials Center
My learning

Topics

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.

PHP
$f = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
echo $f->formatCurrency(1234.5, 'USD');   // $1,234.50

Try it

PHP Guarded use with number_format() fallback

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.

PHP Percentages and ordinals by hand

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

PHP
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

PHP
$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 NumberFormatter throws Error (class not found) without intl.
  • Format only for display. Keep calculations in int cents 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 change MIN_FRACTION_DIGITS and MAX_FRACTION_DIGITS.
  • Rounding mode defaults to half-even; set NumberFormatter::ROUNDING_MODE with ROUND_HALFUP and friends for the result schools and invoices expect.
  • parse() is locale-bound. A German formatter reads 1.234,5 as 1234.5; an English one stops at the comma. A false result means nothing could be parsed.
  • Errors: after a failure, getErrorCode() and getErrorMessage() tell why.
  • Without intl, number_format() can mimic a locale only if you pass its separators yourself; see its page.