NumberFormatter クラス

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

はじめに

プログラムで数値を保存したり操作したりする際には、 ロケールに依存しないバイナリ表現を使用します。 数値を表示するときに、ロケールにあわせた文字列形式に変換します。 たとえば 12345.67 という数値の表記はアメリカでは "12,345.67"、 フランスでは "12 345,67"、そしてドイツでは "12.345,67" となります。

NumberFormatter クラスのメソッドを実行すると、 数値や通貨、パーセンテージなどの値をロケールに応じた形式にフォーマットすることができます。 NumberFormatter はロケールを考慮した処理を行うので、 ロケールごとに別の NumberFormatter を用意する必要があります。 NumberFormatter のメソッドは、浮動小数点数値のような数値を ロケールにあわせた文字列に変換します。

通貨の場合は、通貨用の書式を使用してフォーマッタを作成します。 これは、ロケールにあわせて数値を適切な書式にして通貨記号をつけた文字列を返します。 もちろん、NumberFormatter クラスは為替レートの変換などは考慮しません。 指定した通貨にかかわらず、出力される数値は同じものとなります。 つまり、ロケールによって同じ数値が違う額を表すことになるということです。 9988776.65 という数値を指定したときの結果は次のようになります。

  • 9 988 776,65 € (フランス)
  • 9.988.776,65 € (ドイツ)
  • $9,988,776.65 (アメリカ)

パーセンテージをフォーマットするには、 パーセンテージ用の書式を指定したフォーマッタを作成します。 これを使用すると、たとえば 0.75 のような小数が 75% と表示されるようになります。

spelled-out numbers のような複雑な書式を設定する場合は、 ルールベースの数値フォーマッタを使用します。

クラス概要

class NumberFormatter {
/* 定数 */
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_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_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 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 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 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 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 TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* メソッド */
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
}

定義済み定数

フォーマッタのタイプ

これらのスタイルは numfmt_create() で使用するもので、フォーマッタの形式を定義します。

NumberFormatter::PATTERN_DECIMAL int

パターンで定義する十進形式

NumberFormatter::DECIMAL int

十進形式

NumberFormatter::DECIMAL_COMPACT_SHORT int

コンパクト表記(短縮形)を使った十進形式。例: "23K", "45B"。PHP 8.5.0 および ICU 56 以降で利用可能です。

NumberFormatter::DECIMAL_COMPACT_LONG int

コンパクト表記(長い形式)を使った十進形式。例: "23 thousand", "45 billion"。PHP 8.5.0 および ICU 56 以降で利用可能です。

NumberFormatter::CURRENCY int

通貨形式

NumberFormatter::CURRENCY_ISO int

ISO 通貨形式(例: "USD1.00")。PHP 8.5.0 以降で利用可能です。

NumberFormatter::CURRENCY_PLURAL int

複数形の通貨形式(例: "1.00 US dollar" および "3.00 US dollars")。PHP 8.5.0 以降で利用可能です。

NumberFormatter::CASH_CURRENCY int

現金使用時の通貨記号。例: "NT$3.23" ではなく "NT$3"。PHP 8.5.0 および ICU 54 以降で利用可能です。

NumberFormatter::CURRENCY_STANDARD int

通貨記号。例: "$1.00"。負の値には非会計方式(例: マイナス記号)を使用します。PHP 8.5.0 および ICU 56 以降で利用可能です。

NumberFormatter::PERCENT int

パーセント形式

NumberFormatter::SCIENTIFIC int

科学形式

NumberFormatter::SPELLOUT int

ルールベースの省略しない形式

NumberFormatter::ORDINAL int

ルールベースの序数形式

NumberFormatter::DURATION int

ルールベースの連続形式

NumberFormatter::PATTERN_RULEBASED int

パターンで定義するルールベースの形式

NumberFormatter::CURRENCY_ACCOUNTING int

会計処理のための通貨フォーマット。例: 負の通貨量の場合、-$3.00 ではなく、($3.00) になります。 PHP 7.4.1 と ICU 53 から利用可能です。

NumberFormatter::DEFAULT_STYLE int

そのロケールのデフォルトの形式

NumberFormatter::IGNORE int

PATTERN_DECIMAL のエイリアス

数値フォーマットの指定子

これらの定数は、数値のパースやフォーマットの方法を定義します。 numfmt_format()numfmt_parse() の引数として使用します。

NumberFormatter::TYPE_DEFAULT int

変数の型に由来する型

NumberFormatter::TYPE_INT32 int

32 ビット整数値としてフォーマット/パースする

NumberFormatter::TYPE_INT64 int

64 ビット整数値としてフォーマット/パースする

NumberFormatter::TYPE_DOUBLE int

浮動小数点数値としてフォーマット/パースする

NumberFormatter::TYPE_CURRENCY int

通貨値としてフォーマット/パースする。PHP 8.3.0 以降は非推奨

数値フォーマットの属性

numfmt_get_attribute() および numfmt_set_attribute() で使用する数値フォーマット属性です。

NumberFormatter::PARSE_INT_ONLY int

整数値のみをパースする

NumberFormatter::GROUPING_USED int

グループ区切り文字を使用する

NumberFormatter::DECIMAL_ALWAYS_SHOWN int

常に小数点を表示する

NumberFormatter::MAX_INTEGER_DIGITS int

整数部の最大桁数

NumberFormatter::MIN_INTEGER_DIGITS int

整数部の最小桁数

NumberFormatter::INTEGER_DIGITS int

整数部の桁数

NumberFormatter::MAX_FRACTION_DIGITS int

小数部の最大桁数

NumberFormatter::MIN_FRACTION_DIGITS int

小数部の最小桁数

NumberFormatter::FRACTION_DIGITS int

小数部の桁数

NumberFormatter::MULTIPLIER int

乗数

NumberFormatter::GROUPING_SIZE int

グループ化のサイズ

NumberFormatter::ROUNDING_MODE int

丸めモード

NumberFormatter::ROUNDING_INCREMENT int

切り上げ

NumberFormatter::FORMAT_WIDTH int

format() の出力のパディング幅

NumberFormatter::PADDING_POSITION int

パディングを行う位置。 使用できる引数の値についてはパディング位置に関する定数を参照ください。

NumberFormatter::SECONDARY_GROUPING_SIZE int

第二段階のグループ化のサイズ

NumberFormatter::SIGNIFICANT_DIGITS_USED int

有効数字を使用する

NumberFormatter::MIN_SIGNIFICANT_DIGITS int

有効数字の最小桁数

NumberFormatter::MAX_SIGNIFICANT_DIGITS int

有効数字の最大桁数

NumberFormatter::LENIENT_PARSE int

ルールベースのフォーマットで使用する Lenient パースモード

数値フォーマットのテキスト属性

numfmt_get_text_attribute() および numfmt_set_text_attribute() で使用する数値フォーマットテキスト属性です。

NumberFormatter::POSITIVE_PREFIX int

正の数のプレフィックス

NumberFormatter::POSITIVE_SUFFIX int

正の数のサフィックス

NumberFormatter::NEGATIVE_PREFIX int

負の数のプレフィックス

NumberFormatter::NEGATIVE_SUFFIX int

負の数のサフィックス

NumberFormatter::PADDING_CHARACTER int

余白を埋める際に使用する文字

NumberFormatter::CURRENCY_CODE int

ISO 通貨コード

NumberFormatter::DEFAULT_RULESET int

デフォルトのルールセット。 ルールベースのフォーマッタでのみ有効です。

NumberFormatter::PUBLIC_RULESETS int

パブリックルールセット。 これは、ルールベースのフォーマッタでのみ有効です。 これは読み込み専用の属性です。 パブリックルールセットは文字列として返され、 個々のルールセットは ';' (セミコロン) で区切られています。

シンボルフォーマットの指定子

numfmt_get_symbol() および numfmt_set_symbol() で使用する数値フォーマット記号です。

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL int

小数点

NumberFormatter::GROUPING_SEPARATOR_SYMBOL int

グループ区切り文字

NumberFormatter::PATTERN_SEPARATOR_SYMBOL int

パターン区切り文字

NumberFormatter::PERCENT_SYMBOL int

パーセント記号

NumberFormatter::ZERO_DIGIT_SYMBOL int

ゼロ

NumberFormatter::DIGIT_SYMBOL int

パターン内で数字を表す文字

NumberFormatter::MINUS_SIGN_SYMBOL int

マイナス記号

NumberFormatter::PLUS_SIGN_SYMBOL int

プラス記号

NumberFormatter::CURRENCY_SYMBOL int

通貨記号

NumberFormatter::INTL_CURRENCY_SYMBOL int

国際通貨記号

NumberFormatter::MONETARY_SEPARATOR_SYMBOL int

金額の区切り文字

NumberFormatter::EXPONENTIAL_SYMBOL int

指数記号

NumberFormatter::PERMILL_SYMBOL int

パーミル記号

NumberFormatter::PAD_ESCAPE_SYMBOL int

パディング文字のエスケープ記号

NumberFormatter::INFINITY_SYMBOL int

無限大記号

NumberFormatter::NAN_SYMBOL int

非数値記号

NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL int

有効数字記号

NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL int

金額のグループ区切り文字

丸めモード

numfmt_get_attribute() および numfmt_set_attribute() で、 NumberFormatter::ROUNDING_MODE 属性に使用する丸めモードの値です。

NumberFormatter::ROUND_AWAY_FROM_ZERO

NumberFormatter::ROUND_UP のエイリアス

NumberFormatter::ROUND_CEILING int

正の無限大に向けて丸めるモード

NumberFormatter::ROUND_DOWN int

ゼロに向けて丸めるモード

NumberFormatter::ROUND_FLOOR int

負の無限大に向けて丸めるモード

NumberFormatter::ROUND_HALFDOWN int

"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロに向けて丸めます。

NumberFormatter::ROUND_HALFEVEN int

"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は偶数になるように丸めます。

NumberFormatter::ROUND_HALFODD

"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は奇数になるように丸めます。

NumberFormatter::ROUND_HALFUP int

"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロから離れる方向に丸めます。

NumberFormatter::ROUND_TOWARD_ZERO

NumberFormatter::ROUND_DOWN のエイリアス

NumberFormatter::ROUND_UP int

ゼロから離れる方向に丸めるモード

パディングの指定子

numfmt_get_attribute() および numfmt_set_attribute() で、 NumberFormatter::PADDING_POSITION 属性に使用するパディング位置の値です。

NumberFormatter::PAD_AFTER_PREFIX int

プレフィックスの後にパディング文字を入れる

NumberFormatter::PAD_AFTER_SUFFIX int

サフィックスの後にパディング文字を入れる

NumberFormatter::PAD_BEFORE_PREFIX int

プレフィックスの前にパディング文字を入れる

NumberFormatter::PAD_BEFORE_SUFFIX int

サフィックスの前にパディング文字を入れる

変更履歴

バージョン 説明
8.5.0 NumberFormatter::DECIMAL_COMPACT_SHORTNumberFormatter::DECIMAL_COMPACT_LONGNumberFormatter::CURRENCY_ISONumberFormatter::CURRENCY_PLURALNumberFormatter::CASH_CURRENCYNumberFormatter::CURRENCY_STANDARD が追加されました。
8.4.0 クラス定数が型付けされました。

目次

add a note

User Contributed Notes 5 notes

up
50
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>";
?>
up
8
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); // ↂ

?>
up
3
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.
up
3
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
up
0
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);