PHP str_pad() 完全指南：字串填充長度、方向、多字元填充字符實戰

函數簽名與參數詳解

str_pad(
    string $string,      // 輸入字串
    int $length,         // 目標長度（若 ≤ 原長度則不填充）
    string $pad_string = " ", // 填充字符（可多字元），預設空格
    int $pad_type = STR_PAD_RIGHT // 填充方向常數
): string

方向常數：

• STR_PAD_RIGHT（預設）：右側填充
• STR_PAD_LEFT：左側填充
• STR_PAD_BOTH：兩側填充，左側優先

基本範例

$input = "Alien";

echo str_pad($input, 10);                    // "Alien     " (右填空格)
echo str_pad($input, 10, "-=", STR_PAD_LEFT);  // "-=-=-Alien" (左填多字元)
echo str_pad($input, 10, "_", STR_PAD_BOTH);   // "__Alien___" (兩側填充)
echo str_pad($input, 6, "___");                // "Alien_" (右填，多字元循環)

進階實戰場景

1. 數字前導零補齊（訂單號、編號）

function formatOrderId(int $id, int $width = 8): string {
    return str_pad((string)$id, $width, '0', STR_PAD_LEFT);
}
echo formatOrderId(123);        // 00000123
echo formatOrderId(20240001);   // 20240001

2. 固定寬度表格輸出（CLI 報表）

function tableRow(array $cols, array $widths): string {
    $parts = [];
    foreach ($cols as $i => $col) {
        $parts[] = str_pad($col, $widths[$i], ' ', STR_PAD_RIGHT);
    }
    return '| ' . implode(' | ', $parts) . ' |';
}

$widths = [10, 20, 12, 8];
echo tableRow(['ID', 'Name', 'Price', 'Stock'], $widths);
echo tableRow(['001', 'iPhone 15 Pro', '7999.00', '100'], $widths);
/*
| ID         | Name                 | Price      | Stock   |
| 001        | iPhone 15 Pro        | 7999.00    | 100     |
*/

3. 多字元填充字符循環規則

// 填充字符長度 > 1 時，會循環使用直到達到長度
echo str_pad('A', 10, 'ab');      // Aabababab (右填)
echo str_pad('A', 10, 'ab', STR_PAD_LEFT);  // bababababA
echo str_pad('A', 10, 'ab', STR_PAD_BOTH);  // babAababab

4. 中文字串填充：視覺寬度 vs 字節長度

注意：str_pad 按字節長度計算，非視覺寬度。中文 UTF-8 佔 3 字節，顯示寬度通常為 2。

$str = '測試';
echo str_pad($str, 10, ' '); // 字節長度 6，補 4 空格 → 視覺寬度不對齊

// 解決：用 mb_strwidth 計算視覺寬度
function mb_str_pad($string, $width, $pad = ' ', $type = STR_PAD_RIGHT, $encoding = 'UTF-8') {
    $len = mb_strwidth($string, $encoding);
    if ($len >= $width) return $string;
    $padLen = $width - $len;
    $padStr = str_repeat($pad, ceil($padLen / mb_strwidth($pad, $encoding)));
    switch ($type) {
        case STR_PAD_LEFT:  return $padStr . $string;
        case STR_PAD_BOTH:  $left = (int)($padLen / 2); return str_repeat($pad, $left) . $string . str_repeat($pad, $padLen - $left);
        default:            return $string . $padStr;
    }
}
echo '[' . mb_str_pad('測試', 10, ' ') . ']'; // [測試      ] 視覺對齊

5. 日期時間格式化輔助

function fmtDateTime(int $ts): string {
    return str_pad(date('H', $ts), 2, '0', STR_PAD_LEFT) . ':' .
           str_pad(date('i', $ts), 2, '0', STR_PAD_LEFT) . ':' .
           str_pad(date('s', $ts), 2, '0', STR_PAD_LEFT);
}
// 等同 date('H:i:s')，展示 str_pad 在格式化中的應用

常見錯誤與避坑

效能備註

• 純 C 實現，極快（百萬次/秒級）
• 大量填充時，預先 str_repeat 填充字符再 substr 截取略快於重複呼叫
• CLI 表格輸出建議用 sprintf 格式化字串，可一次完成對齊與格式化

結語

str_pad 是 PHP 字串處理的基石函數，掌握方向常數、多字元循環、中文視覺寬度差異三大核心知識點，即可靈活應對編號補零、報表對齊、格式化輸出等高頻需求。記住：字節 ≠ 視覺寬度，中文場景務必用 mb_strwidth 輔助計算。