PHP strpos() 函數深度解析：查找字串位置的正確姿勢

strpos() 是 PHP 中查找子字串在目標字串中首次出現的索引位置的核心函數。雖然用法簡單，但「返回 0 代表找到且位於開頭」與「返回 false 代表未找到」的特性，是無數新手 Bug 的溫床。本文徹底講透用法、陷阱與最佳實踐。

函數簽名

strpos(string $haystack, string $needle, int $offset = 0): int|false

• $haystack：被搜尋的字串（乾草堆）。
• $needle：要找的子字串（針）。
• $offset（可選）：從指定索引開始搜尋（可為負數，表示從末尾倒數）。

基本範例

<?php
$str = 'Hello world!';
$pos = strpos($str, 'wo');
var_dump($pos); // int(6)

$pos = strpos($str, 'PHP');
var_dump($pos); // bool(false)
?>

核心陷阱：嚴格比較 !== false

❌ 錯誤寫法：

if (strpos($str, 'Hello')) { // 位置 0 被視為 false，條件不成立！
    echo '找到';
}

✅ 正確寫法：

if (strpos($str, 'Hello') !== false) {
    echo '找到於索引 ' . strpos($str, 'Hello');
}

鐵律：永遠使用 !== false 或 === false 判斷，切勿直接用於 if 條件或 !strpos()。

進階用法

1. 從指定位置開始搜尋

$str = 'abcabcabc';
echo strpos($str, 'a', 3); // 3（找到第二個 a）

2. 查找所有出現位置

function strpos_all(string $haystack, string $needle): array {
    $positions = [];
    $offset = 0;
    while (($pos = strpos($haystack, $needle, $offset)) !== false) {
        $positions[] = $pos;
        $offset = $pos + 1;
    }
    return $positions;
}
print_r(strpos_all('ababa', 'aba')); // [0, 2]

3. 大小寫不敏感搜尋

使用 stripos()（PHP 5+ 內建），行為與 strpos() 完全一致，只差不區分大小寫。

效能對比

💡 原則：只需判斷「是否包含」或「位置」時，優先用 strpos() / stripos()。

實戰場景

• 關鍵字過濾：if (stripos($content, '敏感詞') !== false)
• URL 解析：$pos = strpos($url, '?'); $query = $pos !== false ? substr($url, $pos+1) : '';
• CSV/日誌分欄：搭配 strpos 找分隔符位置，再 substr 切割，比 explode 更省記憶體（大檔案流式處理）。
• 模板引擎標籤替換：循環 strpos 找 {{var}} 位置並替換。

常見錯誤總結

1. 忘記 !== false 導致索引 0 被誤判。
2. 混淆 strpos（位置）與 strstr（子字串）的返回值。
3. 在循環中重複呼叫 strpos($str, $needle) 而未更新 $offset，導致無限循環。
4. 對多位元組字串（UTF-8 中文）直接使用，位置會是字節索引而非字符索引。需用 mb_strpos()。

多位元組字串補充：mb_strpos()

$str = '你好世界';
echo strpos($str, '世');     // 6（字節索引）
echo mb_strpos($str, '世');  // 2（字符索引，正確）

處理中文等多位元組編碼時，務必使用 mb_strpos()、mb_stripos()、mb_substr() 系列函數，並確保 mb_internal_encoding('UTF-8') 已設定。

記住「嚴格比較」與「編碼對應」兩大鐵律，strpos() 就能成為你字串處理工具箱中最鋒利的利刃。