PHPのstr_contains関数は、ある文字列の中に、指定した別の文字列が含まれているかどうかをシンプルにチェックするために使用されます。
この関数は、PHP8.0で新しく導入されたもので、それ以前のバージョンでよく使われていたstrpos関数と比較して、より直感的で、かつ安全に「含まれているかどうか」を判定できます。
特に、条件分岐で「この文字列があるかないか」だけを調べたい場合に非常に便利です。
この記事では、str_contains関数の基本的な使い方、引数、戻り値、主要な使用例、そして以前のバージョンのPHPでの代替方法について解説します。
str_contains関数の基本的な構文
str_contains関数の基本的な構文は以下の通りです。
str_contains(string $haystack, string $needle): bool
$haystack: 必須。検索対象となる元の文字列です。$needle: 必須。$haystack内に含まれているかを確認したい文字列です。
引数
引数の詳細についてです。
$haystack (元の文字列)
- 検索対象となる文字列です。
$needle (検索文字列)
$haystack内に含まれているかを確認したい部分文字列です。$needleが空文字列（''）の場合、trueが返されます。
戻り値
$needleが$haystackに含まれている場合は true。
含まれていない場合はfalseが返されます。
重要な点
str_contains関数は大文字と小文字を区別します。大文字と小文字を区別せずに検索したい場合は、mb_stripos関数やstripos関数などの関数を組み合わせる必要があります。str_contains関数はPHP 8.0以降で利用可能です。
str_contains関数を使ってみる
実際にstr_contains関数を使って、動作を確認していきます。
例1：基本的な使い方
文字列に特定のキーワードが含まれているかどうかをシンプルにチェックします。
<?php
$string = "Hello, world!";
// 「world」が含まれているか？
if (str_contains($string, 'world')) {
echo "「world」は文字列に含まれています。" . PHP_EOL;
} else {
echo "「world」は文字列に含まれていません。" . PHP_EOL;
}
// 出力: 「world」は文字列に含まれています。
// 「PHP」が含まれているか？
if (str_contains($string, 'PHP')) {
echo "「PHP」は文字列に含まれています。" . PHP_EOL;
} else {
echo "「PHP」は文字列に含まれていません。" . PHP_EOL;
}
// 出力: 「PHP」は文字列に含まれていません。
$string変数に「Hello, world!」という文字列を格納しています。
次の処理でstr_contains関数を使って、変数に「world」が含まれているか確認しています。
ここでは含まれているので、trueが返ってきます。
次に文字列にPHPが入っているかを確認していますが、ここでは含まれていないのでfalseが返ってきます。
例2：大文字と小文字を区別する挙動
str_contains関数は大文字と小文字を区別します。
<?php
$text = "The quick brown fox.";
// 「FOX」が含まれているか？
if (str_contains($text, 'FOX')) {
echo "「FOX」は文字列に含まれています。" . PHP_EOL;
} else {
echo "「FOX」は文字列に含まれていません。" . PHP_EOL;
}
// 出力: 「FOX」は文字列に含まれていません。
$text文字列に大文字の「FOX」が含まれているか確認しています。
この場合、"fox"は小文字なので、大文字の"FOX"では一致しません。
例3：空文字列を探す文字列に指定した場合
探す文字列が空文字列の場合、常にtrueを返します。
<?php
$string = "some text";
if (str_contains($string, '')) {
echo "空文字列は常に含まれていると判断されます。" . PHP_EOL;
}
// 出力: 空文字列は常に含まれていると判断されます。
str_contains関数で探しているのが空文字なので、上記の例ではtrueが返ってきます。
str_contains関数とstrpos関数の違いと利点
PHP8.0以前では、文字列に特定の文字列が含まれているかどうかのチェックに、strpos関数を使うのが一般的でした。
しかし、strpos関数には落とし穴がありました。
| 関数 | 目的 | 戻り値 | 備考 |
|---|---|---|---|
str_contains |
含まれるかどうかの判定 | bool (true/false) |
PHP 8.0以降で利用可能 |
strpos |
最初の出現位置の取得 | int (インデックス) / false |
0番目の位置で見つかった場合、falseと区別するために厳密比較 (===) が必要 |
strpos関数を使って「文字列が含まれているか」を判定する場合、以下のように書く必要がありました。
// PHP 7.4以前の書き方
$text = "PHP is a popular language.";
// strpos()は、見つからない場合はfalseを、0番目の位置で見つかった場合は0を返す
// 0 == false となるため、厳密な比較 (===) が必須
if (strpos($text, 'PHP') !== false) {
echo "「PHP」が見つかりました。" . PHP_EOL;
}
もし if (strpos($text, 'PHP')) のように書いてしまうと
'PHP'が文字列の先頭（0番目）にある場合、0はfalseと評価されて、if文のブロックが実行されず、意図しない結果になっていました。
str_containsはこの問題を解決します。
戻り値がbool型であるため、厳密な比較を意識することなく、直感的にif文で判定できます。
これにより、コードの可読性が大幅に向上し、バグの発生リスクを減らすことができます。
str_contains関数が使えないときの代替方法
str_contains関数が利用できない古いバージョンのPHPでは、以下のような方法で同様のチェックが可能です。
1. strpos関数と厳密比較を使う
これが最も一般的で推奨される方法です。
<?php
$url = "https://www.example.com";
if (strpos($url, 'https://') !== false) {
echo "URLはHTTPSです。" . PHP_EOL;
}
strpos関数で「https://'」から$url変数の文字列がはじまるか確認しています。
先頭から一致するので、0が返ってくるため、厳密比較で「!==」とする必要があります。
2. strstr関数を使う
strstr関数は、見つかった場合はその位置から元の文字列の最後までを返し、見つからない場合はfalseを返します。
この戻り値を使って真偽値を判定できます。
<?php
$text = "PHP is fun.";
if (strstr($text, 'fun')) {
echo "「fun」が含まれています。" . PHP_EOL;
}
ただし、str_contains関数とは異なり、strstr関数は文字列の残りの部分全体を返してきます。
また、戻り値が空文字列（""）の場合もfalseと評価されるため注意が必要です。
まとめ
PHPのstr_contains関数は、文字列内に特定の文字列が含まれているかどうかをシンプルかつ安全に判定できる非常に便利な関数です。
PHP 8.0以降で導入されたこの関数は、strpos関数のような厳密比較の必要性を取り除き、コードの可読性と保守性を向上させます。
もしPHP 8.0未満の環境で開発している場合は、strpos関数と厳密比較を組み合わせることで、同様の機能を実装することができます。
この関数を理解し、適切に使い分けることで、より堅牢で読みやすいPHPコードを書くことができるでしょう。
コメント