PHP 字串替換只執行一次或 N 次：preg_replace_limit 與 str_replace_once 實作

內建函數限制

• str_replace()、strtr()：全域替換，無次數參數。
• preg_replace()：支援 $limit 參數（第 4 參數），但需正則語法。

方案一：preg_replace 封裝（支援陣列、特殊字元跳脫）

function pregReplaceLimit(
    string|array $pattern,
    string|array $replace,
    string|array $subject,
    int $limit = -1
): string|array {
    $isArray = is_array($subject);
    $subjects = $isArray ? $subject : [$subject];
    $patterns = is_array($pattern) ? $pattern : [$pattern];
    $replaces = is_array($replace) ? $replace : [$replace];

    // 統一長度
    $count = max(count($patterns), count($replaces));
    $patterns = array_pad($patterns, $count, '');
    $replaces = array_pad($replaces, $count, '');

    $results = [];
    foreach ($subjects as $subj) {
        $result = $subj;
        foreach ($patterns as $i => $pat) {
            if ($pat === '') continue;
            $pat = '/' . preg_quote($pat, '/') . '/';
            $result = preg_replace($pat, $replaces[$i], $result, $limit);
        }
        $results[] = $result;
    }
    return $isArray ? $results : $results[0];
}

// 使用
$str = 'abcabbc';
echo pregReplaceLimit('b', 'X', $str, 1); // aXcabbc (只替第一個)
echo pregReplaceLimit('b', 'X', $str, 2); // aXcaXbc (替前兩個)

方案二：純字串操作（無正則、效能更好）

function strReplaceOnce(string $search, string $replace, string $subject): string {
    $pos = strpos($subject, $search);
    if ($pos === false) return $subject;
    return substr_replace($subject, $replace, $pos, strlen($search));
}

function strReplaceLimit(string $search, string $replace, string $subject, int $limit): string {
    if ($limit <= 0) return $subject;
    $len = strlen($search);
    $result = '';
    $pos = 0;
    $count = 0;
    while (($found = strpos($subject, $search, $pos)) !== false && $count < $limit) {
        $result .= substr($subject, $pos, $found - $pos) . $replace;
        $pos = $found + $len;
        $count++;
    }
    $result .= substr($subject, $pos);
    return $result;
}

// 使用
$str = 'abcabbc';
echo strReplaceOnce('b', 'X', $str);      // aXcabbc
echo strReplaceLimit('b', 'X', $str, 2);  // aXcaXbc

效能比較（100 萬字串、替換 3 次）

結論： 純字串操作 strReplaceLimit 效能最佳、無正則負擔，建議優先使用。

多關鍵字各自限制 N 次

function multiReplaceLimit(array $pairs, string $subject, int $limitEach = 1): string {
    // $pairs = ['search1'=>'replace1', 'search2'=>'replace2', ...]
    foreach ($pairs as $search => $replace) {
        $subject = strReplaceLimit($search, $replace, $subject, $limitEach);
    }
    return $subject;
}

$text = 'apple banana apple cherry banana apple';
echo multiReplaceLimit(['apple'=>'A', 'banana'=>'B'], $text, 2);
// A B A cherry B apple (apple 替 2 次、banana 替 2 次)