定義と使い方

PHPバージョン
4.0.6+

mb_strpos()は、文字列内から特定の文字列が最初に出現する位置を検索する関数です。

この関数はstrpos()関数とほぼ同じ機能を持っていますが、日本語・韓国語・中国語のようなマルチバイト文字列（multi-byte string）に対しても安全に動作するという点が大きな違いです。

英語や数字などは1byteですが、日本語・韓国語・中国語などは2byte以上で表現されます。このように、2byte以上のバイトで表現されるものを「multi-byte（マルチバイト）」と呼びます。

特徴

  • multi-byte（マルチバイト）をサポートしています。
  • 対象となる文字列の中で、指定した文字列が最初に出現する位置（インデックス）を返します。
  • 指定した文字列が含まれていない場合はfalseを返します。
  • 大文字と小文字を区別します。

基本例

PHP 
$str = 'はじめまして。ようこそ！';
$substring = 'ようこそ';

$pos = mb_strpos($str, $substring, 0, 'UTF-8');

if ($pos !== false) {
    echo "見つかった位置: $pos";
} else {
    echo '見つかりませんでした。';
}

// 出力: 見つかった位置: 7

/*
 * 注意してください！
 * 文字列のインデックスは0から始まります。
 * 最初の文字のインデックスは0、2番目の文字のインデックスは1です。
 */

日本語におけるstrpos()関数の問題点

strpos()関数は、日本語のようなマルチバイト文字列（multi-byte string）をサポートしていないため、意図しない結果が発生することがあります。

PHP 
$str = 'はじめまして。ようこそ！';
$substring = 'ようこそ';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "見つかった位置: $pos";
} else {
    echo '見つかりませんでした。';
}

// 出力: 見つかった位置: 21 ← 意図しない結果が発生します。

UTF-8のようなマルチバイト文字エンコーディングでは、1文字が複数バイトで表現されるため、strpos()関数のように一般的なバイト数をそのまま基準として文字列を処理すると、予期しない結果を招く可能性があります。

mb_strpos()関数によるstrpos()関数の日本語問題の解決

mb_strpos()関数は、日本語のようなマルチバイト文字列（multi-byte string）に対しても安全に動作するため、strpos()関数における日本語の問題を解決できます。

知っておいてください！
mb_strpos()関数は、strpos()関数の代わりとして、マルチバイト（multi-byte）で安全に動作する関数です。

構文

PHP 
mb_strpos(
    string $haystack,
    string $needle,
    int $offset = 0,
    ?string $encoding = null
): int|false

引数

mb_stpos()関数の引数の説明
$haystack 検索対象となる文字列です。
$needle 検索する文字列です。
  • 大文字と小文字を区別します。
  • PHP 8より前のバージョンでは、空文字列（''）は許可されていません。Warningエラーが発生します。
$offset オプション。検索を開始する0基準のインデックスです。
  • 省略した場合、デフォルト値として0が使用されます。
  • 負の値を指定することもでき、負の値の場合は文字列の末尾から数えた文字数分の位置から検索が開始されます。
$encoding オプション。文字列のエンコーディングを指定します。
デフォルト値はnullで、省略するかnullを渡した場合は、内部文字エンコーディングの値が使用されます。
  • 内部文字エンコーディングが標準エンコーディングである'UTF-8'の場合は、特に指定する必要はありません。
  • 内部エンコーディングが別の値である場合は、一貫した処理結果を得るために、標準エンコーディングである'UTF-8'を明示的に指定してください。

戻り値

対象となる文字列の中で、指定した文字列（$needle）が最初に出現する位置（インデックス）を返します。
文字列の位置は1ではなく0から始まる点に注意してください。

指定した文字列（$needle）が含まれていない場合はfalseを返します。

変更履歴

mb_strpos()関数の変更履歴
バージョン説明
8.0.0 $needleに空文字列（''）を指定できます。
8.0.0 $encodngは、現在ではnullの値を持つことができます。
7.1.0 $offsetに負の値を渡せるようになりました。

注意点

mb_strpos()関数は、大文字と小文字を区別します。

PHP mb_strpos()関数は、大文字と小文字を区別します。 
$str = 'Hello, World!';
$substring = 'world';

$pos = mb_strpos($str, $substring, 0, 'UTF-8');

if ($pos === false) {
    echo "大文字と小文字が一致しないため、'world!'を見つけることができません。";
} else {
    echo "文字列に'world!'が含まれています。";
}

// 出力: "大文字と小文字が一致しないため、'world!'を見つけることができません。"

大文字と小文字を区別せずに文字列内から特定の文字列の位置を検索したい場合は、mb_stripos()関数を使用してください。

文字列のインデックスは0から始まります。
最初の文字のインデックスは0、2番目の文字のインデックスは1です。

PHP 文字列のインデックスは0から始まります。 
$newstring = 'あいうえお かきくけこ';
$pos = mb_strpos($newstring, 'あ', 0, 'UTF-8');

var_dump($pos); // int(0)

PHP 8より前のバージョンでは、検索する文字列に空文字列（''）は許可されていません。

PHP PHP 8より前のバージョンでは、検索する文字列に空文字列（''）は許可されていません。 
$str = 'Hello, World!';
$substring = '';

$pos = mb_strpos($str, $substring, 0, 'UTF-8'); // Warning: mb_strpos(): Empty needle in

この関数の戻り値をブール（boolean）型として使用する場合は注意が必要です。
この関数の戻り値を判定する際は、===演算子を使用してください。

対象となる文字列の中で、指定した文字列の位置が先頭にある場合を想定してみましょう。

この場合、戻り値は0になります。

0は==演算子で比較するとfalseとして評価されます。
実際には指定した文字列が存在しているにもかかわらずfalseと判定されてしまうため、Boolean型として戻り値を判定する場合は、厳密な型比較を行う必要があり、===演算子を使用する必要があります。

PHP Boolean型として戻り値を使用する場合は、===演算子を使用してください。 
$str = 'Hello, World!';
$substring = 'Hello';

$pos = mb_strpos($str, $substring, 0, 'UTF-8');

var_dump($pos); // int(0)

if ($pos === false) {
    echo "文字列に'Hello'を見つけることができません。";
} else {
    echo "文字列に'Hello'が含まれています。";
}

// 出力: "文字列に'Hello'が含まれています。"

参考資料

関連項目