PHP NumberFormatter 怎样按地区格式化金额

PHP 里不要手工拼接货币符号、千分位和小数点。NumberFormatter 可以把地区规则交给 locale，再通过 formatCurrency() 接收 ISO 货币代码，生成适合展示的金额文本。官方手册入口是 https://www.php.net/manual/en/class.numberformatter.php。

把 locale 理解成“怎么显示”，把 currency 理解成“显示哪一种货币”。例如同一个数值交给不同 locale，分组符号、小数分隔符和货币符号位置可能不同；NumberFormatter 只负责格式化，不负责汇率换算。

本文只处理 locale 与 currency 的组合，不把展示文本当成账务金额，也不在格式化器里塞入汇率或舍入后的业务结算结果。

locale 和 currency 分别决定什么

NumberFormatter 创建时需要一个 locale 和样式。金额场景使用 NumberFormatter::CURRENCY，调用 formatCurrency() 时再给出货币代码，例如 CNY、EUR 或 USD。locale 影响数字排列习惯，currency 表示货币种类，两者不要混成一个参数。

比如同一个金额在中文、中国地区和美国地区的显示方式可能不同。这里的“可能”很重要：格式化器读取的是 ICU 和 locale 的规则，不应该在业务代码里假设所有地区都采用相同的小数分隔符或货币符号位置。

怎样创建可复用的地区化金额格式化器

将 formatter 的创建集中起来，调用方只传地区和货币代码。这样可以避免页面、接口和导出任务各自拼接格式，后续要调整默认小数位时也有单一入口。

getErrorCode() !== U_ZERO_ERROR) {
        throw new RuntimeException($formatter->getErrorMessage());
    }

    return $formatter;
}

// locale 决定展示规则，货币代码在 formatCurrency() 调用时传入。
$formatter = createMoneyFormatter('zh_CN');
$display = $formatter->formatCurrency(1234567.89, 'CNY');
echo $display;
?>

示例中的金额只是展示输入，不代表已经完成支付结算。formatCurrency() 的返回值是格式化后的字符串；如果调用方还需要进行加减乘除，应该继续保存业务层的数值，而不是把这段字符串再解析回来。

怎样控制小数位和舍入方式

默认规则通常适合直接展示，但订单、报表和多地区界面可能需要统一最小或最大小数位。可以用 setAttribute() 调整小数位，也可以设置舍入模式。参数改变的是输出文本，不是原始金额。

setAttribute(NumberFormatter::MIN_FRACTION_DIGITS, 2);
$formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);

// HALFUP 只影响格式化文本的舍入，不会修改数据库中的金额。
$formatter->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_HALFUP);

// 货币代码决定显示哪种货币，locale 决定符号和数字分组习惯。
$display = $formatter->formatCurrency(19.995, 'USD');
if ($display === false) {
    // 失败时交给上层记录或返回错误，避免把 false 当作金额字符串。
    throw new RuntimeException($formatter->getErrorMessage());
}
echo $display;
?>

不要为了让所有界面看起来一样，就把不同币种都强行改成同一套符号位置。若产品要求统一两位小数，可以只覆盖小数位；货币符号、负数表现和分组符号仍应由目标 locale 提供。

多地区调用时怎样处理错误

多地区接口通常会把 locale 和货币代码作为配置或受控枚举，而不是完全信任用户输入。创建 formatter 后要检查错误码，调用 formatCurrency() 后也要判断返回值。这样一旦环境缺少 intl、locale 不可用或输入格式不被接受，错误会停留在边界层。

 ['locale' => 'zh_CN', 'currency' => 'CNY'],
    'us' => ['locale' => 'en_US', 'currency' => 'USD'],
    'de' => ['locale' => 'de_DE', 'currency' => 'EUR'],
];

function formatMoney(float $amount, string $region, array $locales): string
{
    if (!isset($locales[$region])) {
        // 未配置的地区不能偷偷降级成服务器默认 locale。
        throw new InvalidArgumentException('不支持的地区');
    }

    $config = $locales[$region];
    $formatter = new NumberFormatter($config['locale'], NumberFormatter::CURRENCY);
    $result = $formatter->formatCurrency($amount, $config['currency']);

    if ($result === false) {
        // 保留 ICU 提供的错误信息，便于日志和监控定位。
        throw new RuntimeException($formatter->getErrorMessage());
    }

    return $result;
}
?>

这层函数只返回展示字符串，不承担汇率转换。若业务真的要把 CNY 换算成 EUR，需要由独立的汇率或定价服务提供输入，随后再把换算后的业务金额交给 formatter 展示。

展示金额与业务金额如何分层

一个稳定的接口通常同时保留机器可读金额和面向用户的显示文本：前者用于计算、排序和审计，后者用于当前 locale 的页面展示。不要把带货币符号的字符串当作唯一金额来源，也不要用 NumberFormatter 代替账务精度策略。

如果接口只返回一个字段，至少要明确它是业务数值还是展示文本；更稳妥的做法是同时返回数值、货币代码和按当前地区生成的展示值，让不同客户端按自己的显示需求使用。

常见问题

NumberFormatter 会自动换算汇率吗？

不会。它只按 locale 和货币格式规则生成字符串，同一个数值不会因为传入另一种货币代码就自动变成另一种货币的等值金额。

locale 和 currency 可以随便互换吗？

不建议。locale 决定地区化显示习惯，currency 是货币代码；可以用美国 locale 显示 EUR，也可以按业务需要让不同地区看到同一币种，但两者承担的语义不同。

formatCurrency() 返回 false 怎么办？

把它当作格式化失败处理，读取 formatter 的错误码和错误消息并交给上层。不要直接把 false 拼接进接口响应，也不要用服务器默认地区静默替代原配置。

金额应该用浮点数还是字符串传给 formatter？

本文只讨论展示格式。业务金额的精度和存储类型应由账务模型决定；进入 NumberFormatter 前，确保传入的是已经确定含义的数值，格式化后的字符串只用于展示。