PHP 金额格式化时怎样指定货币和区域

PHP 金额格式化不要只调用 number_format() 再手动拼接货币符号。需要同时处理千位分组、小数分隔符、负数样式和币种时，应该让 NumberFormatter 使用明确的 ICU locale，再通过 formatCurrency() 传入三位 ISO 4217 货币代码。locale 决定“怎样写”，货币代码决定“写哪一种钱”，它们不是一回事。

官方地址：https://www.php.net/manual/en/class.numberformatter.php

最小写法是 new NumberFormatter('zh_CN', NumberFormatter::CURRENCY)，然后调用 formatCurrency($amount, 'CNY')。不要把 locale 当成汇率，也不要把显示结果当成记账结果。

先把金额展示的资产边界划清

金额字符串看起来只是页面文本，实际上包含几个容易混在一起的契约：原始金额、展示区域、货币代码、舍入规则和最终文案。安全地处理它，第一步不是选择一个“看起来像人民币”的符号，而是先确认服务端保存的金额是什么币种、页面需要什么区域，以及谁有权决定这两个值。

NumberFormatter 按指定 locale 格式化数字和货币。官方文档也特别说明，它不了解汇率：同一个数值传入不同货币代码，只会改变货币标识和相关格式，不会把美元金额换算成人民币。汇率计算必须属于独立的业务服务或财务规则。

区域决定写法，货币代码决定币种

例如，en_US 常见的是英文区域的数字书写方式，de_DE 使用德国区域的分隔习惯，zh_CN 则是中文区域。它们可以和不同的货币代码组合：在德国区域展示 USD，仍然是美元，只是采用德国区域的书写习惯。

这也是为什么不建议只依赖 locale 的默认货币。业务页面的语言区域和订单本身的结算币种经常不是同一个概念。一个面向中文用户的美元报价，可能使用 zh_CN 作为界面区域，同时传入 USD 作为货币代码。

最小写法：用 formatCurrency 指定货币

下面的函数把允许的区域和币种作为调用方已经确认过的参数。formatCurrency() 的第二个参数是三位 ISO 4217 货币代码；返回值是格式化字符串，失败时可能返回 false，所以不要无条件把返回值直接写进响应。

formatCurrency($amount, $currency);

    // 格式化失败时抛出错误，避免把 false 静默拼进页面。
    if ($formatted === false) {
        throw new RuntimeException($formatter->getErrorMessage());
    }

    return $formatted;
}

// locale 是展示区域，CNY 是明确的货币代码。
echo formatMoney(1234.5, 'zh_CN', 'CNY') . PHP_EOL;
echo formatMoney(1234.5, 'en_US', 'USD') . PHP_EOL;
echo formatMoney(1234.5, 'de_DE', 'EUR') . PHP_EOL;

这个例子没有在页面层拼接 ￥、$ 或 €。符号的位置、分组和小数分隔交给 ICU 规则，代码只明确传入金额、区域和货币代码。不同 ICU 数据版本可能使某些符号或负数外观略有差异，不能把展示字符串当成跨环境永远不变的协议。

把用户传入的区域和币种放进允许集合

如果 locale 来自请求参数，不能因为它是字符串就直接交给格式化器。应先把用户可选值映射到产品允许的区域集合；货币也一样。这样做不是为了“防止格式化器被攻击”，而是为了避免用户通过未支持的区域改变页面契约、日志样式或财务展示含义。

 'zh_CN',
    'en-US' => 'en_US',
    'de-DE' => 'de_DE',
];
const ALLOWED_CURRENCIES = ['CNY', 'USD', 'EUR'];

function resolveLocale(string $requested): string
{
    // 未知区域回退到产品默认值，不能把请求值原样写进日志或页面。
    return ALLOWED_LOCALES[$requested] ?? ALLOWED_LOCALES['zh-CN'];
}

function resolveCurrency(string $requested): string
{
    // 币种集合应与订单或账户配置保持一致，而不是由页面随意决定。
    if (!in_array($requested, ALLOWED_CURRENCIES, true)) {
        throw new InvalidArgumentException('不支持的货币');
    }
    return $requested;
}

允许集合只解决“能不能展示”的输入边界，不解决“金额是否真的应该是这个币种”。订单币种仍应从服务端的订单模型或明确业务配置中读取；如果客户端同时提交金额和币种，服务端要以可信业务记录为准。

小数位、舍入和浮点数不要混为一谈

货币格式通常会显示固定的小数位，但展示位数不等于业务精度。NumberFormatter 可以通过属性调整最小和最大小数位，也可以设置舍入模式；这只影响格式化输出。它不会把浮点数变成精确的财务记账类型，也不会替代金额计算。

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

    $result = $formatter->formatCurrency($amount, $currency);
    if ($result === false) {
        throw new RuntimeException('金额展示格式化失败：' . $formatter->getErrorMessage());
    }
    return $result;
}

// 生产记账应优先使用整数最小货币单位或明确的高精度方案。
echo formatInvoiceTotal(19.995, 'zh_CN', 'CNY') . PHP_EOL;

这里的 19.995 只是说明展示边界，不能把示例中的浮点输入当成财务计算建议。实际系统可以用整数分、专用高精度库或数据库定点类型保存金额，再在展示层转换为格式化器需要的数值。记录舍入政策时，还要说明是在哪一步舍入：单行、税额、折扣还是最终合计。

不要用 setlocale 代替 NumberFormatter 的区域契约

PHP 的 setlocale() 修改的是进程或线程相关的 locale 状态，官方文档提醒，在多线程服务器 API 中可能出现其他代码改变全局状态的情况。它适合处理明确依赖 C locale 的旧接口，但不适合作为每个请求动态切换金额展示区域的唯一边界。

使用 NumberFormatter 时，区域直接绑定在格式器对象上：同一个请求可以分别创建 zh_CN 和 en_US 两个对象，不必修改全局 locale。多个格式器也更容易在测试和审计时表达“这一段文本使用哪个区域”。

上线前用一张小清单复查

金额格式化的风险通常不是“符号少了一个”，而是边界没有写清。可以在代码评审和回归测试中逐项确认：

• locale 是否来自允许集合，并且与页面语言或展示区域的含义一致。
• 货币代码是否来自服务端可信业务数据，而不是直接信任客户端提交。
• 是否通过 formatCurrency() 明确传入三位 ISO 4217 代码。
• 是否检查 false 返回并保留格式化器的错误信息。
• 是否把汇率换算、记账精度和展示舍入放在独立的业务边界。
• 是否覆盖正数、负数、零、较大整数、小数位和至少两个区域。

常见误区是看到页面出现 $ 就认为金额已经是美元，或看到 ￥ 就认为系统完成了人民币换算。正确做法是同时查看原始金额模型、货币代码和展示 locale。NumberFormatter 负责把已确定的数值写成适合读者阅读的文本，不负责替业务系统决定钱从哪里来、是否需要兑换和最终如何入账。

相关问题

locale 是不是就等于货币？

不是。locale 描述区域化的数字和文本格式，货币代码描述币种。一个中文区域可以展示 USD，一个德国区域也可以展示 EUR 以外的币种。

formatCurrency() 会自动做汇率换算吗？

不会。它只按 formatter 规则格式化传入数值，并使用传入的货币代码显示货币信息。

可以用 number_format() 手动拼符号吗？

简单内部报表可以，但跨区域和多币种页面容易漏掉符号位置、分组分隔符和负数规则。需要 ICU 区域规则时，优先使用 NumberFormatter。

NumberFormatter 返回 false 怎么办？

不要静默输出。读取 getErrorMessage()，将错误交给调用方或统一异常处理，并检查 locale、扩展和货币代码是否属于支持范围。