【PHP8.x】mb_strpos関数の使い方

<?php

/**
 * PHPのmb_strpos関数の基本的な使い方と、
 * マルチバイト文字列におけるstrpos関数との違いを示すサンプルコードです。
 * システムエンジニアを目指す初心者の方が「mb_strpos not working」という
 * 問題に直面した際の理解を助けることを目的としています。
 */
function demonstrateMbStrposUsage(): void
{
    // 検索対象のマルチバイト文字列（日本語を含む）
    $haystack = "こんにちは世界、PHPの世界へようこそ！";
    // 検索する部分文字列
    $needle = "世界";
    // 見つからない部分文字列
    $notFoundNeedle = "Python";

    echo "検索対象の文字列: \"" . $haystack . "\"\n\n";

    // --- strpos の問題点 (マルチバイト文字列の場合) ---
    // strpos はバイト単位で文字列を処理するため、日本語のようなマルチバイト文字を含む文字列では
    // 期待通りの結果（文字オフセット）が得られないことがあります。
    // これが「mb_strpos not working」と感じる原因の一つです。
    echo "--- strpos を使用した例 (非推奨) ---\n";
    $posStrpos = strpos($haystack, $needle);
    if ($posStrpos !== false) {
        // strposはバイトオフセットを返します。多くの場合、期待する文字オフセットとは異なります。
        echo "strpos で \"" . $needle . "\" を検索: 位置 " . $posStrpos . " (バイトオフセット)\n";
    } else {
        // 日本語文字列では、strposが正しく検索できない場合があります。
        echo "strpos で \"" . $needle . "\" は見つかりませんでした (期待通りの結果ではないかもしれません)。\n";
    }
    echo "\n";

    // --- mb_strpos の使い方 (マルチバイト文字列で推奨) ---
    // mb_strpos はマルチバイトセーフな関数で、文字単位で文字列を処理します。
    echo "--- mb_strpos を使用した例 (推奨) ---\n";

    // 1. 検索文字列が見つかる場合
    $posMbStrpos = mb_strpos($haystack, $needle);
    if ($posMbStrpos !== false) {
        // mb_strpos は0から始まる文字オフセットを返します。
        // 例: "こ"(0) "ん"(1) "に"(2) "ち"(3) "は"(4) "世"(5) -> '世界'は5番目の文字から始まる
        echo "mb_strpos で \"" . $needle . "\" を検索: 位置 " . $posMbStrpos . " (0始まりの文字オフセット)\n";
    } else {
        // 通常、このケースでは見つかるはずですが、念のため
        echo "mb_strpos で \"" . $needle . "\" は見つかりませんでした。\n";
    }

    // 2. 検索文字列が見つからない場合
    $posMbStrposNotFound = mb_strpos($haystack, $notFoundNeedle);
    if ($posMbStrposNotFound !== false) {
        echo "mb_strpos で \"" . $notFoundNeedle . "\" を検索: 位置 " . $posMbStrposNotFound . "\n";
    } else {
        // 検索文字列が見つからない場合、mb_strpos は false を返します。
        // 0 (文字列の先頭で見つかった場合) と false を厳密に区別することが重要です。
        echo "mb_strpos で \"" . $notFoundNeedle . "\" は見つかりませんでした (期待通り false が返ります)。\n";
    }

    // 3. 検索開始位置 (offset) の指定
    echo "\n--- mb_strpos でオフセットを指定した例 ---\n";
    // 最初の '世界' の次から検索を開始し、2つ目の '世界' を見つける例
    $firstWorldPos = mb_strpos($haystack, $needle); // 最初の '世界' の位置 (文字オフセット5)
    if ($firstWorldPos !== false) {
        // 検索開始位置は、最初の '世界' の直後からとします。
        // mb_strlenで'世界'の文字数を取得し、オフセットを計算します。
        $offset = $firstWorldPos + mb_strlen($needle); // 例: 5 + 2 = 7
        $secondWorldPos = mb_strpos($haystack, $needle, $offset);
        if ($secondWorldPos !== false) {
            echo "オフセット " . $offset . " から次の \"" . $needle . "\" を検索: 位置 " . $secondWorldPos . "\n";
            // 結果: "こんにちは世界、PHPの世界へようこそ！" 中の2つ目の'世界'は、文字オフセット12から始まる。
        } else {
            echo "オフセット " . $offset . " 以降に \"" . $needle . "\" は見つかりませんでした。\n";
        }
    } else {
        echo "最初の \"" . $needle . "\" が見つからなかったため、オフセット検索は行いませんでした。\n";
    }

    // 補足: encoding 引数について
    // 通常はPHPの内部エンコーディング (mb_internal_encoding() で設定) が使用されます。
    // 異なるエンコーディングの文字列を明示的に扱う場合は、第四引数で指定できます。
    // 例: mb_strpos($haystack, $needle, 0, 'EUC-JP');
    // ただし、haystackとneedleのエンコーディングが一致している必要があります。
}

// 関数を実行
demonstrateMbStrposUsage();

mb_strpos関数は、PHP 8.4で利用できる、マルチバイト文字列（日本語など）から特定の部分文字列が最初に現れる位置を、文字数で検索するための関数です。一般的なstrpos関数が文字列をバイト単位で処理するのに対し、mb_strposは文字単位で処理します。そのため、日本語のようなマルチバイト文字を含む文字列を扱う際に、正確な文字位置（オフセット）を取得するために推奨されます。strposをマルチバイト文字列に適用して意図しない結果となり、「mb_strpos not working」といった誤解が生じるケースがありますが、これはstrposがバイトオフセットを返すのに対し、mb_strposは文字オフセットを返すためです。

この関数は、最初の引数$haystackに検索対象の文字列、二番目の引数$needleに検索したい部分文字列を指定します。三番目の引数$offsetでは、検索を開始する文字位置を0から始まる整数で指定できます（デフォルトは0）。四番目の引数$encodingは、文字列のエンコーディングを明示的に指定する場合に使用しますが、通常はPHPの内部エンコーディングが適用されます。

戻り値は、$needleが$haystack内で見つかった場合、0から始まる文字オフセット（整数）を返します。見つからなかった場合はfalseを返します。文字列の先頭で見つかった場合は0を返すため、0とfalseを厳密に区別するために、比較演算子!==を使用することが重要です。mb_strposを使うことで、マルチバイト文字列の検索を安全かつ正確に行うことができます。

<?php

/**
 * UTF-8文字列内で部分文字列の位置を検索するサンプルコードです。
 * mb_strpos関数はマルチバイト文字（日本語、絵文字など）を正しく扱い、
 * バイト数ではなく文字数で位置を返します。
 * システムエンジニアにとって、特にWebアプリケーション開発で日本語などを扱う際に重要です。
 */
function findStringPositionMb(string $haystack, string $needle, int $offset = 0): void
{
    echo "--- mb_strpos 検索例 ---\n";
    echo "検索対象文字列: '{$haystack}'\n";
    echo "検索する部分文字列: '{$needle}'\n";
    echo "開始オフセット (文字数): {$offset}\n";

    // mb_strpos を使用して、UTF-8エンコーディングで部分文字列を検索します。
    // 見つかった場合は、0から始まる文字位置（バイト位置ではない）を返します。
    // 見つからない場合は false を返します。
    $position = mb_strpos($haystack, $needle, $offset, 'UTF-8');

    if ($position !== false) {
        echo "結果: 部分文字列は {$position} 番目の文字の位置で見つかりました。\n";
    } else {
        echo "結果: 部分文字列は見つかりませんでした。\n";
    }
    echo "-------------------------\n\n";
}

// 実際の使用例

// 1. 基本的な日本語文字列での検索
findStringPositionMb("こんにちは世界！", "世界");

// 2. 開始オフセットを指定した検索 (2文字目から「にち」を検索)
// 「こ」が0文字目、「ん」が1文字目なので、「にち」は2文字目から始まります。
findStringPositionMb("こんにちは世界！", "にち", 1);

// 3. 検索文字列が見つからない場合
findStringPositionMb("Hello World", "PHP");

// 4. オフセットが大きすぎて見つからない場合
// 「世界」は「こんにちは世界！」の4文字目から始まります。
// オフセットを5にすると、検索範囲外になるため見つかりません。
findStringPositionMb("こんにちは世界！", "世界", 5);

// 5. 絵文字を含む文字列での検索 (mb_strposが絵文字も1文字として数えることを示す)
findStringPositionMb("🚀 PHPを学ぼう！", "学ぼう");

// 6. オフセットを指定して絵文字をスキップして検索
// 「🚀」が0文字目なので、「PHP」は2文字目から始まります。
findStringPositionMb("🚀 PHPを学ぼう！", "PHP", 1);

PHPのmb_strpos関数は、UTF-8などのマルチバイト文字列（日本語、絵文字など）において、指定した部分文字列が最初に現れる位置を検索するために利用します。通常のstrpos関数がバイト数を基準とするのに対し、mb_strposはマルチバイト文字を正しく1文字として扱い、バイト数ではなく文字数で位置を返します。システムエンジニアにとって、特にWebアプリケーション開発で日本語などの多様な言語を扱う際に、文字化けや意図しない結果を防ぐために重要な関数です。

この関数は、検索対象の文字列を$haystack、検索する部分文字列を$needle、検索を開始する文字位置を$offset（デフォルトは0）、そして文字列のエンコーディングを$encodingとして受け取ります。通常、$encodingには'UTF-8'を指定します。部分文字列が見つかった場合、戻り値としてその開始位置を0から始まる文字数で返します。例えば「こんにちは」で「こ」は0文字目、「ん」は1文字目となります。部分文字列が見つからなかった場合はfalseを返します。

サンプルコードでは、基本的な日本語文字列での検索や、$offsetを指定して途中から検索する例を示しています。また、検索文字列が見つからない場合や、オフセットが検索範囲を超えて見つからなくなる場合の挙動も確認できます。さらに、絵文字を含む文字列の検索例からは、mb_strposが絵文字も1文字として正確に数えることが分かります。これにより、様々な文字セットを含む文字列操作を正確に行うことが可能です。