PHP sprintf() 函數深度解析：格式化字串與浮點數精度控制

sprintf() 是 PHP 格式化字串的核心函數，依據格式字串將參數轉為指定格式並回傳（不直接輸出）。本文重點解析浮點數格式化、寬度與精度控制，以及整數與浮點數參數傳遞的陷阱。

基本語法

sprintf(string $format, mixed ...$values): string

• $format：格式字串，包含一般文字與格式規範（以 % 開頭）。
• $values：對應格式規範的參數值。
• 回傳格式化後的字串。

常用格式規範

浮點數精度與寬度控制：%[flags][width][.precision]f

<?php
$num = 3.1415926;

// 預設：小數 6 位，無寬度限制
echo sprintf('%f', $num);        // "3.141593" (四捨五入)

// 指定總寬度 9、小數 3 位，右對齊（前面補空格）
echo sprintf('%9.3f', $num);     // "    3.142"

// 指定總寬度 9、小數 3 位，左對齊（後面補空格）
echo sprintf('%-9.3f', $num);    // "3.142    "

// 僅指定精度，不限寬度
echo sprintf('%.3f', $num);      // "3.142"

// 0 填充寬度（前面補 0）
echo sprintf('%09.3f', $num);    // "0003.142"

// 強制顯示正負號
echo sprintf('%+f', $num);       // "+3.141593"
echo sprintf('%+f', -$num);      // "-3.141593"
?>

關鍵陷阱：整數參數對應 %f 格式

<?php
$num = 100; // 整數

// 錯誤示範：直接傳整數給 %f
$result1 = sprintf('%.2f', $num); 
// 結果："100.00" （看似正確，但行為未定義）

// 正確做法：明確轉型為 float
$result2 = sprintf('%.2f', (float)$num); 
// 結果："100.00" （明確語意）

// 更明確：使用浮點數字面值
$result3 = sprintf('%.2f', 100.0); 
?>

原因：sprintf 為 C 風格可變參數函數，格式字串在執行期解析。若格式為 %f 但實際傳入整數，屬於未定義行為（Undefined Behavior），視平台/編譯器可能導致錯誤結果或崩潰。務必確保參數型別與格式規範匹配。

實用範例：貨幣格式化

<?php
function formatCurrency(float $amount, string $currency = 'TWD', int $decimals = 2): string {
    $sign = $amount < 0 ? '-' : '';
    $abs = abs($amount);
    // 整數部分加千分位，小數固定位數
    return $sign . $currency . ' ' . number_format($abs, $decimals, '.', ',');
}

echo formatCurrency(1234567.89); // "TWD 1,234,567.89"
echo formatCurrency(-99.5);      // "-TWD 99.50"
?>

註：純貨幣格式化建議用 NumberFormatter (intl 擴展) 支援地區化。

相關函數比較

總結

• 掌握 %[width].[precision]f 控制浮點數顯示格式。
• 參數型別必須與格式規範匹配，整數勿直接對應 %f、%e、%g。
• 複雜地區化格式（貨幣、數字分組）優先使用 NumberFormatter。
• 格式字串若來自使用者輸入，注意格式化字串攻擊（Format String Vulnerability），避免直接帶入 sprintf($userInput, ...)。