函數原型

substr_replace(
    string|array $string,
    string|array $replace,
    int $offset,
    int|null $length = null
): string|array

• offset ≥ 0：從開頭算起；offset < 0：從結尾算起
• length > 0：替換長度；length < 0：保留結尾長度；length = 0：插入不替換
• 支援陣列批次處理

基礎範例

$str = '123456789';

substr_replace($str, '###', 0);        // ### (從 0 開始替換到結尾)
substr_replace($str, '###', 5);        // 12345### (從索引 5 替換到結尾)
substr_replace($str, '###', 0, 0);     // ###123456789 (索引 0 插入)
substr_replace($str, '###', 8, -2);    // 12345678###9 (索引 8 到倒數第 2)
substr_replace($str, '###', -6, -1);   // 123###9 (倒數第 6 到倒數第 1)
substr_replace($str, '###', -1);       // 12345678### (倒數第 1 插入)
substr_replace($str, '###', 1, -1);    // 1###9 (索引 1 到倒數第 1)
substr_replace($str, '###', 1, 1);     // 1###3456789 (索引 1 長度 1)

實用範例：刪除/插入/替換區段

$var = 'ABCDEFGH:/MNRPQR/';

substr_replace($var, 'bob', 0);                    // bob (全替換)
substr_replace($var, 'bob', 0, strlen($var));      // bob (全替換，明確長度)
substr_replace($var, 'bob', 0, 0);                 // bobABCDEFGH:/MNRPQR/ (開頭插入)
substr_replace($var, 'bob', 10, -1);               // ABCDEFGH:/bob/ (替換 MNRPQR)
substr_replace($var, 'bob', -7, -1);               // ABCDEFGH:/bob/ (負索引替換)
substr_replace($var, '', 10, -1);                  // ABCDEFGH:// (刪除 MNRPQR)

實用範例：長字串截斷加省略號

$long = 'abcdefghijklmnopqrstuvwxyz0123456789z.jpg';
$sep = '...';
$maxLen = 25 - strlen($sep); // 22
$start = $maxLen / 2;        // 11
$trunc = strlen($long) - $maxLen; // 35 - 22 = 13

echo substr_replace($long, $sep, $start, $trunc);
// abcdefghijk...456789z.jpg

封裝函數：智慧截斷 (保留單字完整)

function truncate($text, $maxLen) {
    $text = html_entity_decode($text, ENT_QUOTES);
    if (mb_strlen($text) <= $maxLen) {
        return htmlentities($text, ENT_QUOTES);
    }
    
    $text = mb_substr($text, 0, $maxLen);
    $lastSpace = mb_strrpos($text, ' ');
    if ($lastSpace !== false) {
        $text = mb_substr($text, 0, $lastSpace);
    }
    // 移除結尾標點
    $text = rtrim($text, ".,;:!?");
    
    return htmlentities($text . '...', ENT_QUOTES);
}

echo truncate('welcome to nowamagic, welcome to nowamagic', 35);
// welcome to nowamagic...

中文處理注意

• substr_replace 按**位元組**操作，中文 (UTF-8 一字 3 位元組) 會導致亂碼
• 中文環境請用 mb_substr/mb_strcut + 重組，或 mbstring 函數族
• PHP 7.2+ mb_substr_replace 仍未內建，需自行實作