PHP Intl按地区格式化金额与小数的实现方法

做多地区结算页时，金额显示最容易出现两个误区：把逗号和小数点写死，或者先用字符串拼接再补货币符号。更稳妥的做法是让 PHP Intl 的 NumberFormatter 根据 locale 负责展示规则，再单独设置小数位和舍入模式。这样同一份数值可以输出不同地区习惯的货币与普通小数格式。

官方地址：https://www.php.net/intl

金额展示用 NumberFormatter::CURRENCY，普通小数用 DECIMAL；locale 决定分组符号、货币位置和小数符号，FRACTION_DIGITS 与 ROUNDING_MODE 再决定显示精度。结算数据仍应在业务层用整数分或高精度方案保存。

先把 locale、模式和数据精度分开

Intl 是 ICU 的 PHP 封装，Number Formatter 本身既能按本地化规则格式化数字，也能解析数字。初始化时要先选择模式：金额使用 NumberFormatter::CURRENCY，数量、比例或重量使用 NumberFormatter::DECIMAL。locale 只改变展示约定，不会替你决定数据库字段的精度，也不会把浮点数变成精确金额。

用 CURRENCY 输出不同地区的金额

创建格式化器后，用 formatCurrency() 传入数值和三字母 ISO 4217 货币代码。下面的示例只展示格式化结果，实际业务应在调用前完成金额校验和精度转换。

formatCurrency($amount, 'EUR');

if ($formatted === false) {
    // 格式化失败时不要把 false 当作可展示的金额继续输出。
    throw new RuntimeException($formatter->getErrorMessage());
}

echo $formatted;
// 典型结果：1.234.567,89 €
?>

切换为 en_US 后，分组符号和货币位置会随 locale 改变。不要只替换 € 或逗号，因为符号、空格和小数位都属于同一套区域化规则。官方文档也明确说明货币参数应使用三字母代码，返回值失败时为 false。

固定小数位并选择舍入方式

默认格式化会按照格式器规则进行舍入。如果页面协议要求始终显示两位小数，可以设置 FRACTION_DIGITS；如果业务明确要求只截断、不进位，再设置 ROUNDING_MODE 为 ROUND_DOWN。这两个设置表达的是展示策略，不是对原始金额做永久改写。

setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

$rounded = $formatter->format(3.789);

// 只有明确需要截断展示时才使用 ROUND_DOWN，避免误解为四舍五入。
$formatter->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);
$truncated = $formatter->format(3.789);

if ($rounded === false || $truncated === false) {
    throw new RuntimeException($formatter->getErrorMessage());
}

printf("舍入：%s；截断：%s\n", $rounded, $truncated);
?>

这个区别适合放在测试用例里固定下来：3.789 在两位小数下，默认结果是 3.79，ROUND_DOWN 的结果是 3.78。若页面需要货币符号，则继续使用 CURRENCY 模式，并在同一格式器上设置相应属性。

普通数量用 pattern 绑定单位

重量、容量等数据不应该伪装成货币。可以用 DECIMAL 模式再调用 setPattern()，例如把数值格式化为带 kg 的展示。pattern 遵循 ICU DecimalFormat 语法，设置失败时应读取错误信息；规则型格式器不能使用这个方法。

setPattern('#0.# kg')) {
    throw new RuntimeException($formatter->getErrorMessage());
}

$weight = $formatter->format(1234.56);
if ($weight === false) {
    throw new RuntimeException($formatter->getErrorMessage());
}

echo $weight;
// 典型结果：1234,6 kg
?>

如果只是普通小数而不需要单位，优先使用属性控制最大小数位；如果需要完全自定义显示骨架，再使用 pattern。两者不要为了“看起来一致”混用，否则后续维护时很难判断哪个规则在生效。

上线前固定三条边界

最后把 zh_CN、en_US、de_DE 等实际支持的 locale 加入回归样例，检查货币代码、负数、零值和超过保留位数的输入。这样能把区域化展示问题限制在格式层，避免把 UI 输出规则误当成业务计算。

常见疑问

NumberFormatter 能代替金额存储吗？

不能。它的职责是格式化和解析；金额应以整数最小单位或适合业务的高精度数值保存，展示时再交给 formatter。

为什么同一个金额在不同 locale 下符号位置不同？

货币位置、分组符号和小数符号都来自 locale 的区域化规则。不要手工拼接符号来覆盖其中一部分。