いっしー@Webエンジニア
トップページポートフォリオプログラミング言語ITニュースIT用語辞典ブログ

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

作成日: 更新日:

iconv_strpos関数は、マルチバイト文字列の中から、指定した文字エンコーディングに基づいて、別のマルチバイト文字列が最初に現れる位置を見つける関数です。PHPの標準関数であるstrposと似ていますが、strposがバイト単位で文字列を処理するのに対し、iconv_strposは指定された文字エンコーディング（例えばUTF-8やEUC-JPなど）を考慮して文字単位で検索を行います。このため、日本語や中国語のように1文字が複数のバイトで表現される言語の文字列を正確に扱う際に非常に重要です。

この関数を使用することで、例えば日本語の文章の中から特定の単語がどこに位置するかを、文字化けや誤認識なく正確に検出することができます。検索対象となる元の文字列、見つけたい部分文字列、検索を開始する位置（オフセット）、そして文字列のエンコーディングを指定します。検索が成功すると、部分文字列が最初に現れる位置が0から始まる文字数で返されます。もし部分文字列が見つからなかった場合は、論理値のfalseが返されます。ウェブサイトやアプリケーションが多言語に対応する場合、文字エンコーディングを意識した文字列処理は必須であり、この関数はそのような場面で国際化されたコンテンツを適切に処理するために役立ちます。

基本的な使い方

構文(syntax)

<?php
$text = "こんにちは世界"; // 検索対象の文字列
$search_string = "世界"; // 検索する部分文字列
$offset = 0; // 検索を開始するオフセット（バイト単位）。デフォルトは0。
$encoding = 'UTF-8'; // 文字列のエンコーディングを指定

// iconv_strpos() は、マルチバイト文字列内で部分文字列が最初に出現する位置（バイトオフセット）を検索します。
// 見つからない場合は false を返します。
$position = iconv_strpos($text, $search_string, $offset, $encoding);

if ($position !== false) {
    echo "部分文字列「{$search_string}」は、{$text} の {$position} バイト目に見つかりました。\n";
} else {
    echo "部分文字列「{$search_string}」は見つかりませんでした。\n";
}
?>

引数(parameters)

string $haystack, string $needle, int $offset = 0, ?string $encoding = null

  • string $haystack: 検索対象の文字列
  • string $needle: 検索する文字列
  • int $offset = 0: 検索を開始する位置（デフォルトは0）
  • ?string $encoding = null: 文字コードを指定（nullの場合は内部エンコーディングを使用）

戻り値(return)

int|false

指定された文字列内で、最初に見つかった検索文字列の位置をバイト単位で返します。見つからなかった場合は false を返します。

サンプルコード

PHP iconv_strpos でマルチバイト文字列を検索する

<?php

/**
 * 文字列 $haystack の中で、最初に文字列 $needle が現れる位置を返します。
 * マルチバイト文字列を扱う場合に適しています。
 *
 * @param string $haystack 検索対象の文字列
 * @param string $needle   検索する文字列
 * @param int    $offset   検索を開始するオフセット位置 (デフォルト: 0)
 * @param string|null $encoding 文字エンコーディング (デフォルト: 内部文字エンコーディング)
 *
 * @return int|false 文字列が見つかった場合は最初の位置を返し、見つからなかった場合は false を返します。
 */
function findNeedleInHaystack(string $haystack, string $needle, int $offset = 0, ?string $encoding = null): int|false
{
    // iconv_strpos を使用して、文字列 $haystack 内の $needle の位置を検索します。
    $position = iconv_strpos($haystack, $needle, $offset, $encoding);

    return $position;
}

// 使用例
$haystack = "こんにちは世界、こんにちはPHP！";
$needle = "PHP";

$position = findNeedleInHaystack($haystack, $needle);

if ($position !== false) {
    echo "文字列 '$needle' は位置 " . $position . " に見つかりました。\n";
} else {
    echo "文字列 '$needle' は見つかりませんでした。\n";
}

// オフセットを指定して検索
$position_offset = findNeedleInHaystack($haystack, "こんにちは", 5);

if ($position_offset !== false) {
    echo "文字列 'こんにちは' は位置 " . $position_offset . " (オフセットあり) に見つかりました。\n";
} else {
    echo "文字列 'こんにちは' (オフセットあり) は見つかりませんでした。\n";
}
?>

iconv_strpos関数は、文字列$haystackの中で、文字列$needleが最初に現れる位置を検索する関数です。マルチバイト文字を扱う場合に、文字エンコーディングを考慮して正しく位置を特定するために使用されます。

引数$haystackには検索対象となる文字列を指定します。引数$needleには検索する文字列を指定します。引数$offsetは省略可能な引数で、検索を開始する位置を数値で指定します。デフォルト値は0です。引数$encodingも省略可能な引数で、文字エンコーディングを指定します。nullを指定した場合、内部文字エンコーディングが使用されます。

関数は、$needleが$haystack内で見つかった場合、最初に見つかった位置を整数の数値で返します。見つからなかった場合はfalseを返します。

サンプルコードでは、findNeedleInHaystack関数を作成し、iconv_strposをラップしています。この関数を使用して、文字列"こんにちは世界、こんにちはPHP！"の中から"PHP"という文字列を検索しています。また、オフセットを指定して"こんにちは"という文字列を検索する例も示しています。検索結果に応じて、見つかった位置または見つからなかった旨のメッセージを出力します。iconv_strposは、文字列の検索処理において、文字コードを意識する必要がある場合に非常に有効な関数です。

iconv_strpos関数は、マルチバイト文字を扱う際にstrposの代わりに利用できる関数です。文字エンコーディングを指定しない場合、PHPの内部文字エンコーディングが使用されます。検索対象の文字列と検索文字列のエンコーディングが異なる場合、予期しない結果になる可能性があるため、encoding引数で明示的に指定することを推奨します。また、オフセットは文字数で指定します。戻り値は文字列が見つかった位置（先頭は0）ですが、見つからなかった場合はfalseを返します。厳密な比較演算子（!==）を使用して、falseかどうかを判定してください。PHP8.0以降、falseとの比較に==を使用すると警告が発生します。

【PHP8.x】iconv_strpos関数の使い方 | いっしー@Webエンジニア