naisi_format_amount

将十进制金额格式化为带千分位的显示字符串。 全程按十进制处理，固定使用 HALF_UP 舍入；支持超出 PHP 整数范围的金额。 仅接受原始签名类型，弱类型调用也不转换；类型不匹配直接返回 false。 需要与其他金额接口相同的 LICENSE/PROOF 授权及 DATA capability。

函数签名

function naisi_format_amount(string $amount, int $decimals = 2, bool $fixed_decimals = true): string|false

调用前提

应用入口先调用 naisi_is_ext_license_valid 并确认返回 true。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：LICENSE；执行模式：PROOF。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

参数

$amount

• 类型：string
• 必填：是
• 默认值：无
• 方向：输入参数。

1～256 字节 ASCII 十进制金额，完整匹配 [+-]?[0-9]+(?:\.[0-9]+)?；允许前导零及超过六位的输入小数，拒绝空白、千分位、科学计数法和 NUL。不得先经 float 转换。

$decimals

• 类型：int
• 必填：否
• 默认值：2
• 方向：输入参数。

目标小数位数，支持 0～6，默认 2；0 表示舍入到整数并隐藏小数点。

$fixed_decimals

• 类型：bool
• 必填：否
• 默认值：true
• 方向：输入参数。

true 固定输出指定小数位并补零；false 去除小数末尾零及空小数点。decimals 为 0 时不影响输出；零遵循同一规则且不保留负号。

返回值

类型：string|false

成功返回带英文逗号千分位的金额字符串；参数类型不匹配、非法内容、精度越界、未授权或处理失败返回 false。

调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

$amount = '-1001.0007919';
$decimals = 1;
$fixed_decimals = true;

$result = naisi_format_amount($amount, $decimals, $fixed_decimals);
var_export($result);

金额精度与失败规则

三个金额接口均只接受声明的原始 PHP 类型，弱类型调用也不隐式转换。金额字符串为 1～256 字节，完整匹配 [+-]?[0-9]+(?:\.[0-9]+)?；支持正负号、前导零和超过六位的输入小数，不接受空白、千分位、科学计数法、货币符号、NUL、.5 或 1.。目标精度支持每个整数值 0～6，默认 2。

金额从 JSON、数据库读取到业务传递均保留十进制字符串，不经过 float/double。只有显式缩放转换才输出经过范围检查的整数；缩放整数对应 64 位 PHP 和 MySQL BIGINT SIGNED，范围为 -9223372036854775808～9223372036854775807。每个字段的写入和读取精度必须一致。

类型不匹配、无效内容、精度或舍入模式错误、转换越界及授权失败返回 false；用 === false 判断失败，整数 0 和字符串 "0" 都可能是合法结果。参数数量错误仍遵循 PHP 规则。

升级与相关接口

金额展示使用 naisi_format_amount，金额与缩放整数转换分别使用 naisi_amount_to_scaled_int 和 naisi_scaled_int_to_amount。

旧 naisi_normalize_amount() 已从当前源码移除，没有兼容包装。它与缩放整数还原不是同一操作，迁移时先确认原始数据含义。naisi_format_amount() 的旧 $price、$show_decimals、$show_zero_decimals 参数已改为 $amount、$decimals、$fixed_decimals；位置调用和命名参数调用均需同步。格式化结果只用于展示，不回写为计算金额。

版本信息

• 自版本：1.0.6
• 实现模块：formatting
• 授权类别：LICENSE / PROOF
• 失败回退：false
• 文档同步：2026-10-18