PHP str_pad() 實現卡號/編號不足位數自動補零完全指南

函數速覽

str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT): string

• $string：原始字符串
• $length：目標長度（若小於原長度，不截斷，直接返回原字符串）
• $pad_string：填充字符，默認空格，可為多字符（會循環截取）
• $pad_type：填充方向
  • STR_PAD_LEFT：左側填充（補零常用）
  • STR_PAD_RIGHT：右側填充（默認）
  • STR_PAD_BOTH：兩側填充，奇數額外字符分配給右側

核心場景：生成固定長度卡號/訂單號/員工編號

基本示例：數字遞增補零

<?php
$cardCount = 10;
$cards = [];
for ($i = 1; $i <= $cardCount; $i++) {
    // 左側補零至 10 位
    $cards[] = str_pad($i, 10, '0', STR_PAD_LEFT);
}
print_r($cards);
/* 輸出：
Array
(
    [0] => 0000000001
    [1] => 0000000002
    ...
    [9] => 0000000010
)
*/

進階：帶前綴的業務編號

<?php
function generateCode($prefix, $number, $totalLength = 12) {
    // 計算數字部分需佔用長度
    $numLength = $totalLength - strlen($prefix);
    if ($numLength < 1) throw new InvalidArgumentException('Prefix too long');
    $paddedNum = str_pad($number, $numLength, '0', STR_PAD_LEFT);
    return $prefix . $paddedNum;
}

echo generateCode('ORD', 42);       // ORD000000042
echo generateCode('USR', 1001, 10); // USR0001001

批量生成不重複卡號（結合隨機數）

<?php
function generateUniqueCards($count, $length = 12, $prefix = 'CARD') {
    $codes = [];
    $numLength = $length - strlen($prefix);
    $max = pow(10, $numLength) - 1;
    if ($count > $max) throw new Exception('Count exceeds capacity');

    while (count($codes) < $count) {
        $rand = mt_rand(0, $max);
        $code = $prefix . str_pad($rand, $numLength, '0', STR_PAD_LEFT);
        $codes[$code] = true; // 去重
    }
    return array_keys($codes);
}

$cards = generateUniqueCards(5000, 14, 'VIP');
echo "Generated: " . count($cards) . " unique codes.\n";

常見陷阱與避坑指南

1. 多字符填充字符串的截取行為

<?php
echo str_pad('A', 5, 'XY', STR_PAD_LEFT); // XYXYA (非 XYXYA)
echo str_pad('A', 5, '123', STR_PAD_LEFT); // 12312A
// 規則：填充字符串循環使用，最後截斷至目標長度

2. 負數長度參數

PHP 8.0+ 拋出 ValueError；舊版本返回原字符串。建議顯式校驗 $length > 0。

3. 多字節字符（中文）長度計算

<?php
$str = '中文';
echo strlen($str);        // 6 (UTF-8 字節數)
echo mb_strlen($str);     // 2 (字符數)
echo str_pad($str, 5, '0', STR_PAD_LEFT); // 000中文 (按字節填充，視覺寬度不準)
// 如需按顯示寬度對齊，需結合 mb_strwidth / 視覺寬度庫處理

4. 浮點數科學計數法陷阱

<?php
$num = 123456789012345;
echo str_pad($num, 20, '0', STR_PAD_LEFT);
// 可能輸出：000001.23456789012345E+14 (科學計數法字符串)
// 解決：先用 number_format 或 sprintf 格式化
echo str_pad(number_format($num, 0, '', ''), 20, '0', STR_PAD_LEFT);

性能優化建議

• str_pad 為 C 級函數，性能極高，單次調用納秒級，無需優化。
• 批量生成時，預分配數組 $arr = []; $arr[] = ... 避免擴容開銷。
• 極大量生成（百萬級）可考慮 sprintf('%010d', $i) 替代，語義更明確且略快：

<?php
// sprintf 格式化補零（僅限數字）
for ($i = 1; $i <= 1000000; $i++) {
    $codes[] = sprintf('%010d', $i); // 10 位補零
}

對比：str_pad vs sprintf vs 手動拼接

總結

str_pad() 是 PHP 實現固定長度編碼（卡號、訂單號、工單號等）的**首選工具**，語法簡潔、功能完整、性能優異。掌握其四大參數含義、多字符填充規則、多字節字符限制，並結合 sprintf 針對純數字場景優化，即可輕松應對各類業務編號生成需求。記住核心口訣：**左補零用 STR_PAD_LEFT，目標長度要算清，填充字符可自定，批量生成不重複。**