# 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 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;
/* 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::DECIMAL_COMPACT_SHORT` int
  Decimal format expressed using compact notation (short form), e.g. "23K", "45B". Available as of PHP 8.5.0 and ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Decimal format expressed using compact notation (long form), e.g. "23 thousand", "45 billion". Available as of PHP 8.5.0 and ICU 56.
`NumberFormatter::CURRENCY` int
  Currency format
`NumberFormatter::CURRENCY_ISO` int
  ISO currency format (e.g., "USD1.00"). Available as of PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Pluralized currency format (e.g., "1.00 US dollar" and "3.00 US dollars"). Available as of PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Currency symbol given CASH usage, e.g., "NT$3" instead of "NT$3.23". Available as of PHP 8.5.0 and ICU 54
`NumberFormatter::CURRENCY_STANDARD` int
  Currency symbol, e.g., "$1.00", using non-accounting style for negative values (e.g. minus sign). Available as of PHP 8.5.0 and ICU 56.
`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.

## See Also

- » ICU formatting documentation
- » ICU number formatters
- » ICU decimal formatters
- » ICU rule-based number formatters

## Changelog

Version | Description
--- | ---
8.5.0 | Added `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | The class constants are now typed.

## Table of Contents

- 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open