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

Copy
1<?php
2
3/**
4 * マルチバイト文字列において、大文字小文字を区別せずに文字列の最初の出現位置を検索します。
5 *
6 * mb_strpos関数は通常、大文字小文字を区別して検索するため、
7 * この関数では検索対象 ($haystack) と検索文字列 ($needle) の両方を
8 * 一時的に同じケース（全て小文字）に変換してから検索を行います。
9 *
10 * @param string $haystack 検索対象の文字列。
11 * @param string $needle 検索する文字列。
12 * @param int $offset 検索を開始するオフセット。0から始まります。
13 * @param ?string $encoding 使用するエンコーディング。nullの場合は内部エンコーディングが使用されます。
14 * @return int|false 検索文字列が見つかった場合はその位置（0から始まる）、見つからなかった場合はfalse。
15 */
16function mb_strpos_case_insensitive(string $haystack, string $needle, int $offset = 0, ?string $encoding = null): int|false
17{
18    // 検索対象と検索文字列を同じケース（全て小文字）に変換します。
19    // mb_strtolower関数はマルチバイト文字列に対応しており、指定されたエンコーディングで変換します。
20    // エンコーディングがnullの場合、PHPの内部エンコーディング設定が使用されます。
21    $lowerHaystack = mb_strtolower($haystack, $encoding);
22    $lowerNeedle = mb_strtolower($needle, $encoding);
23
24    // 小文字に変換された文字列同士でmb_strpos関数を実行し、出現位置を取得します。
25    // これにより、元の文字列の大文字小文字に関わらず、目的の文字列を検索できます。
26    return mb_strpos($lowerHaystack, $lowerNeedle, $offset, $encoding);
27}
28
29// --- 以下は mb_strpos_case_insensitive 関数の使用例です ---
30
31// PHPの内部エンコーディングを設定します。
32// マルチバイト文字を正しく扱うために重要です。通常はスクリプトの冒頭や設定ファイルで行います。
33mb_internal_encoding("UTF-8");
34
35$text = "こんにちは、世界！ PHP の mb_strpos は素晴らしい。";
36
37// 例1: 小文字の検索文字列
38$search1 = "php";
39$pos1 = mb_strpos_case_insensitive($text, $search1);
40if ($pos1 !== false) {
41    echo "検索文字列 '{$search1}' は位置 {$pos1} で見つかりました。\n";
42} else {
43    echo "検索文字列 '{$search1}' は見つかりませんでした。\n";
44}
45
46// 例2: 大文字小文字が混在した検索文字列
47$search2 = "Mb_Strpos";
48$pos2 = mb_strpos_case_insensitive($text, $search2);
49if ($pos2 !== false) {
50    echo "検索文字列 '{$search2}' は位置 {$pos2} で見つかりました。\n";
51} else {
52    echo "検索文字列 '{$search2}' は見つかりませんでした。\n";
53}
54
55// 例3: 存在しない検索文字列
56$search3 = "存在しない単語";
57$pos3 = mb_strpos_case_insensitive($text, $search3);
58if ($pos3 !== false) {
59    echo "検索文字列 '{$search3}' は位置 {$pos3} で見つかりました。\n";
60} else {
61    echo "検索文字列 '{$search3}' は見つかりませんでした。\n";
62}
63
64// 例4: オフセットを指定した検索
65$text_long = "Apple, Banana, apple, Cherry.";
66$search4 = "apple";
67// 最初の "apple" (実際は "Apple") は0文字目に見つかります。
68$pos4_offset0 = mb_strpos_case_insensitive($text_long, $search4, 0);
69echo "オフセット0から '{$search4}' を検索: 位置 {$pos4_offset0}\n";
70
71// 最初の見つかった位置以降から次の "apple" を検索します。
72$pos4_offset_after_first = mb_strpos_case_insensitive($text_long, $search4, $pos4_offset0 + mb_strlen($search4));
73echo "最初の '{$search4}' 以降から検索: 位置 {$pos4_offset_after_first}\n";

PHPのmb_strpos関数は、日本語のようなマルチバイト文字を含む文字列から、別の文字列が最初に現れる位置を検索する機能を提供します。この関数は、検索時に大文字と小文字を区別するのが標準的な挙動です。

提供されたmb_strpos_case_insensitive関数は、このmb_strposの特性を応用し、大文字小文字を区別せずに文字列を検索できるようにカスタムされています。この関数は、まずmb_strtolower関数を使って、検索対象の文字列（$haystack）と検索したい文字列（$needle）の両方を一時的に全て小文字に変換します。その後、小文字に変換された文字列同士でmb_strposを実行することで、元の文字列の大文字小文字に関わらず目的の文字列を見つけ出します。

引数について、$haystackは検索される元の文字列、$needleは探したい文字列、$offsetは検索を開始する文字列内の位置（0から開始）、$encodingは文字列の文字コード（省略時はPHPの内部エンコーディング）をそれぞれ指定します。

戻り値は、検索文字列が見つかった場合、その文字列が$haystack内で始まる位置を0から始まる整数で返します。もし見つからなかった場合はfalseが返されます。

マルチバイト文字列を正しく扱うためには、mb_internal_encoding()関数を用いて適切なエンコーディング（例："UTF-8"）をスクリプトの冒頭などで設定することが重要です。

Copy
1<?php
2
3/**
4 * PHPのmb_strpos関数の基本的な使い方と、
5 * マルチバイト文字列におけるstrpos関数との違いを示すサンプルコードです。
6 * システムエンジニアを目指す初心者の方が「mb_strpos not working」という
7 * 問題に直面した際の理解を助けることを目的としています。
8 */
9function demonstrateMbStrposUsage(): void
10{
11    // 検索対象のマルチバイト文字列（日本語を含む）
12    $haystack = "こんにちは世界、PHPの世界へようこそ！";
13    // 検索する部分文字列
14    $needle = "世界";
15    // 見つからない部分文字列
16    $notFoundNeedle = "Python";
17
18    echo "検索対象の文字列: \"" . $haystack . "\"\n\n";
19
20    // --- strpos の問題点 (マルチバイト文字列の場合) ---
21    // strpos はバイト単位で文字列を処理するため、日本語のようなマルチバイト文字を含む文字列では
22    // 期待通りの結果（文字オフセット）が得られないことがあります。
23    // これが「mb_strpos not working」と感じる原因の一つです。
24    echo "--- strpos を使用した例 (非推奨) ---\n";
25    $posStrpos = strpos($haystack, $needle);
26    if ($posStrpos !== false) {
27        // strposはバイトオフセットを返します。多くの場合、期待する文字オフセットとは異なります。
28        echo "strpos で \"" . $needle . "\" を検索: 位置 " . $posStrpos . " (バイトオフセット)\n";
29    } else {
30        // 日本語文字列では、strposが正しく検索できない場合があります。
31        echo "strpos で \"" . $needle . "\" は見つかりませんでした (期待通りの結果ではないかもしれません)。\n";
32    }
33    echo "\n";
34
35    // --- mb_strpos の使い方 (マルチバイト文字列で推奨) ---
36    // mb_strpos はマルチバイトセーフな関数で、文字単位で文字列を処理します。
37    echo "--- mb_strpos を使用した例 (推奨) ---\n";
38
39    // 1. 検索文字列が見つかる場合
40    $posMbStrpos = mb_strpos($haystack, $needle);
41    if ($posMbStrpos !== false) {
42        // mb_strpos は0から始まる文字オフセットを返します。
43        // 例: "こ"(0) "ん"(1) "に"(2) "ち"(3) "は"(4) "世"(5) -> '世界'は5番目の文字から始まる
44        echo "mb_strpos で \"" . $needle . "\" を検索: 位置 " . $posMbStrpos . " (0始まりの文字オフセット)\n";
45    } else {
46        // 通常、このケースでは見つかるはずですが、念のため
47        echo "mb_strpos で \"" . $needle . "\" は見つかりませんでした。\n";
48    }
49
50    // 2. 検索文字列が見つからない場合
51    $posMbStrposNotFound = mb_strpos($haystack, $notFoundNeedle);
52    if ($posMbStrposNotFound !== false) {
53        echo "mb_strpos で \"" . $notFoundNeedle . "\" を検索: 位置 " . $posMbStrposNotFound . "\n";
54    } else {
55        // 検索文字列が見つからない場合、mb_strpos は false を返します。
56        // 0 (文字列の先頭で見つかった場合) と false を厳密に区別することが重要です。
57        echo "mb_strpos で \"" . $notFoundNeedle . "\" は見つかりませんでした (期待通り false が返ります)。\n";
58    }
59
60    // 3. 検索開始位置 (offset) の指定
61    echo "\n--- mb_strpos でオフセットを指定した例 ---\n";
62    // 最初の '世界' の次から検索を開始し、2つ目の '世界' を見つける例
63    $firstWorldPos = mb_strpos($haystack, $needle); // 最初の '世界' の位置 (文字オフセット5)
64    if ($firstWorldPos !== false) {
65        // 検索開始位置は、最初の '世界' の直後からとします。
66        // mb_strlenで'世界'の文字数を取得し、オフセットを計算します。
67        $offset = $firstWorldPos + mb_strlen($needle); // 例: 5 + 2 = 7
68        $secondWorldPos = mb_strpos($haystack, $needle, $offset);
69        if ($secondWorldPos !== false) {
70            echo "オフセット " . $offset . " から次の \"" . $needle . "\" を検索: 位置 " . $secondWorldPos . "\n";
71            // 結果: "こんにちは世界、PHPの世界へようこそ！" 中の2つ目の'世界'は、文字オフセット12から始まる。
72        } else {
73            echo "オフセット " . $offset . " 以降に \"" . $needle . "\" は見つかりませんでした。\n";
74        }
75    } else {
76        echo "最初の \"" . $needle . "\" が見つからなかったため、オフセット検索は行いませんでした。\n";
77    }
78
79    // 補足: encoding 引数について
80    // 通常はPHPの内部エンコーディング (mb_internal_encoding() で設定) が使用されます。
81    // 異なるエンコーディングの文字列を明示的に扱う場合は、第四引数で指定できます。
82    // 例: mb_strpos($haystack, $needle, 0, 'EUC-JP');
83    // ただし、haystackとneedleのエンコーディングが一致している必要があります。
84}
85
86// 関数を実行
87demonstrateMbStrposUsage();

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を使うことで、マルチバイト文字列の検索を安全かつ正確に行うことができます。

Copy
1<?php
2
3/**
4 * UTF-8文字列内で部分文字列の位置を検索するサンプルコードです。
5 * mb_strpos関数はマルチバイト文字（日本語、絵文字など）を正しく扱い、
6 * バイト数ではなく文字数で位置を返します。
7 * システムエンジニアにとって、特にWebアプリケーション開発で日本語などを扱う際に重要です。
8 */
9function findStringPositionMb(string $haystack, string $needle, int $offset = 0): void
10{
11    echo "--- mb_strpos 検索例 ---\n";
12    echo "検索対象文字列: '{$haystack}'\n";
13    echo "検索する部分文字列: '{$needle}'\n";
14    echo "開始オフセット (文字数): {$offset}\n";
15
16    // mb_strpos を使用して、UTF-8エンコーディングで部分文字列を検索します。
17    // 見つかった場合は、0から始まる文字位置（バイト位置ではない）を返します。
18    // 見つからない場合は false を返します。
19    $position = mb_strpos($haystack, $needle, $offset, 'UTF-8');
20
21    if ($position !== false) {
22        echo "結果: 部分文字列は {$position} 番目の文字の位置で見つかりました。\n";
23    } else {
24        echo "結果: 部分文字列は見つかりませんでした。\n";
25    }
26    echo "-------------------------\n\n";
27}
28
29// 実際の使用例
30
31// 1. 基本的な日本語文字列での検索
32findStringPositionMb("こんにちは世界！", "世界");
33
34// 2. 開始オフセットを指定した検索 (2文字目から「にち」を検索)
35// 「こ」が0文字目、「ん」が1文字目なので、「にち」は2文字目から始まります。
36findStringPositionMb("こんにちは世界！", "にち", 1);
37
38// 3. 検索文字列が見つからない場合
39findStringPositionMb("Hello World", "PHP");
40
41// 4. オフセットが大きすぎて見つからない場合
42// 「世界」は「こんにちは世界！」の4文字目から始まります。
43// オフセットを5にすると、検索範囲外になるため見つかりません。
44findStringPositionMb("こんにちは世界！", "世界", 5);
45
46// 5. 絵文字を含む文字列での検索 (mb_strposが絵文字も1文字として数えることを示す)
47findStringPositionMb("🚀 PHPを学ぼう！", "学ぼう");
48
49// 6. オフセットを指定して絵文字をスキップして検索
50// 「🚀」が0文字目なので、「PHP」は2文字目から始まります。
51findStringPositionMb("🚀 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文字として正確に数えることが分かります。これにより、様々な文字セットを含む文字列操作を正確に行うことが可能です。

Copy
1<?php
2
3/**
4 * Demonstrates the key difference between strpos() and mb_strpos()
5 * when working with strings that contain multi-byte characters (e.g., UTF-8).
6 *
7 * - strpos(): Operates on byte offsets. For multi-byte character encodings,
8 *             a single character can consist of multiple bytes, leading to
9 *             unexpected results when counting characters.
10 * - mb_strpos(): Operates on character offsets. It correctly handles
11 *                multi-byte character encodings, providing accurate character positions.
12 *
13 * This function also illustrates their identical behavior with single-byte strings.
14 */
15function demonstrateStringPositionFunctions(): void
16{
17    // Set internal encoding to UTF-8 for consistent multi-byte string handling.
18    // This is a good practice when working with mb_* functions.
19    mb_internal_encoding("UTF-8");
20
21    echo "--- Multi-byte String Example (Japanese UTF-8) ---" . PHP_EOL;
22
23    // A string containing multi-byte Japanese characters.
24    $multibyteString = "こんにちは世界！"; // "Hello world!" in Japanese
25    $searchChar      = "世界";          // Searching for "world"
26
27    echo "Original String: '" . $multibyteString . "'" . PHP_EOL;
28    echo "Searching for:   '" . $searchChar . "'" . PHP_EOL;
29
30    // 1. Using strpos() - byte-aware
31    // Each Japanese character in UTF-8 typically occupies 3 bytes.
32    // 'こ', 'ん', 'に', 'ち', 'は' are 5 characters * 3 bytes/char = 15 bytes.
33    // So, "世界" starts at the 15th byte offset.
34    $strposResult = strpos($multibyteString, $searchChar);
35    echo "strpos() result: ";
36    if ($strposResult !== false) {
37        echo "Found at byte offset " . $strposResult . PHP_EOL;
38    } else {
39        echo "Not found (or incorrect byte sequence match)." . PHP_EOL;
40    }
41    // Expected output: Found at byte offset 15
42
43    // 2. Using mb_strpos() - character-aware
44    // The 'encoding' argument is explicitly set to 'UTF-8' for clarity and robustness.
45    // 'こ' (0), 'ん' (1), 'に' (2), 'ち' (3), 'は' (4).
46    // "世界" starts at the 5th character offset.
47    $mbStrposResult = mb_strpos($multibyteString, $searchChar, 0, 'UTF-8');
48    echo "mb_strpos() result: ";
49    if ($mbStrposResult !== false) {
50        echo "Found at character offset " . $mbStrposResult . PHP_EOL;
51    } else {
52        echo "Not found." . PHP_EOL;
53    }
54    // Expected output: Found at character offset 5
55
56    echo PHP_EOL;
57    echo "--- Single-byte String Example (English ASCII) ---" . PHP_EOL;
58
59    // A string containing only single-byte characters.
60    $singlebyteString = "Hello World!";
61    $searchString     = "World";
62
63    echo "Original String: '" . $singlebyteString . "'" . PHP_EOL;
64    echo "Searching for:   '" . $searchString . "'" . PHP_EOL;
65
66    // 1. Using strpos()
67    // 'H'(0), 'e'(1), 'l'(2), 'l'(3), 'o'(4), ' '(5). "World" starts at index 6.
68    $strposSingleResult = strpos($singlebyteString, $searchString);
69    echo "strpos() result: ";
70    if ($strposSingleResult !== false) {
71        echo "Found at offset " . $strposSingleResult . PHP_EOL;
72    } else {
73        echo "Not found." . PHP_EOL;
74    }
75    // Expected output: Found at offset 6
76
77    // 2. Using mb_strpos()
78    // For single-byte strings, mb_strpos() behaves identically to strpos().
79    $mbStrposSingleResult = mb_strpos($singlebyteString, $searchString, 0, 'UTF-8');
80    echo "mb_strpos() result: ";
81    if ($mbStrposSingleResult !== false) {
82        echo "Found at offset " . $mbStrposSingleResult . PHP_EOL;
83    } else {
84        echo "Not found." . PHP_EOL;
85    }
86    // Expected output: Found at offset 6
87}
88
89// Execute the demonstration function to see the results.
90demonstrateStringPositionFunctions();
91
92?>

mb_strpos関数は、指定された文字列の中から特定の文字列が何文字目に現れるかを探す際に使用します。特に日本語のようなマルチバイト文字を含む文字列を扱う場合に非常に重要で、PHP 8で利用できます。

PHPの標準関数であるstrposも同様に文字列内の位置を検索しますが、strposがバイト単位で位置を数えるのに対し、mb_strposは文字エンコーディングを考慮して文字単位で数える点が大きな違いです。例えば、UTF-8エンコーディングの日本語では1文字が複数バイトで構成されるため、strposでは意図しないバイトオフセットが返される可能性がありますが、mb_strposは正しい文字オフセットを返します。

サンプルコードでは、mb_strposは$haystack（検索対象の文字列）の中から$needle（検索する文字列）が最初に現れる位置を、$offset（検索を開始する文字位置、デフォルトは0）以降で検索します。$encoding引数で文字エンコーディングを指定できますが、省略した場合はmb_internal_encodingで設定されたエンコーディングが使用されます。見つかった場合はその位置を整数値で、見つからなかった場合はfalseを返します。

「こんにちは世界！」という日本語の文字列から「世界」を探す例では、strposがバイト単位で数えて15というオフセットを返すのに対し、mb_strposは文字単位で数えて「こんにちは」の5文字の次から始まるため、5という文字オフセットを正しく返しています。一方、「Hello World!」のようなシングルバイト文字のみの文字列では、両者ともに文字数とバイト数が一致するため、同じ6というオフセットを返します。このように、マルチバイト文字を扱う際にはmb_strposを使用することで、期待通りの文字位置を取得できます。