PHP 字符串包含检测：从 str_contains 到 preg_match 的全面指南332

```html

在现代 Web 开发中，PHP 作为一种强大的脚本语言，广泛应用于各种场景。字符串操作是任何编程语言中都不可或缺的核心任务之一，而在 PHP 中，检测一个字符串是否包含另一个子字符串更是日常开发中最常见的需求。无论是验证用户输入、解析日志文件、处理 URL 参数，还是构建复杂的文本处理逻辑，高效且准确地判断字符串包含关系至关重要。本文将作为一份详尽的指南，深入探讨 PHP 中检测字符串包含的各种方法，从简洁现代的 `str_contains()` 到功能强大的正则表达式 `preg_match()`，涵盖它们的用法、特点、性能考量以及最佳实践，旨在帮助 PHP 开发者选择最适合其特定场景的工具。

PHP 8+ 的现代之选：str_contains()

随着 PHP 8.0 的发布，一个备受期待的函数 `str_contains()` 正式加入核心。这个函数的设计目标是提供一个清晰、直观且高性能的方式来检查字符串是否包含子字符串。它直接返回一个布尔值，极大地简化了代码逻辑，并提升了可读性。

用法与特性

`str_contains(string $haystack, string $needle): bool`

`$haystack`: 要搜索的主字符串。
`$needle`: 要查找的子字符串。
返回 `true` 如果 `$haystack` 包含 `$needle`，否则返回 `false`。
区分大小写。

示例

<?php
$text = "Hello, world! Welcome to PHP.";
$search1 = "world";
$search2 = "PHP";
$search3 = "php"; // 小写
$search4 = "example";
// 包含 'world' 吗？
if (str_contains($text, $search1)) {
echo "'$text' 包含 '$search1'."; // 输出: 'Hello, world! Welcome to PHP.' 包含 'world'.
}
// 包含 'PHP' 吗？
if (str_contains($text, $search2)) {
echo "'$text' 包含 '$search2'."; // 输出: 'Hello, world! Welcome to PHP.' 包含 'PHP'.
}
// 包含 'php' 吗？ (区分大小写)
if (str_contains($text, $search3)) {
echo "'$text' 包含 '$search3'.";
} else {
echo "'$text' 不包含 '$search3' (区分大小写)."; // 输出: 'Hello, world! Welcome to PHP.' 不包含 'php' (区分大小写).
}
// 包含 'example' 吗？
if (!str_contains($text, $search4)) {
echo "'$text' 不包含 '$search4'."; // 输出: 'Hello, world! Welcome to PHP.' 不包含 'example'.
}
?>

优势

`str_contains()` 的主要优势在于其简洁性、高可读性和优化的内部实现带来的高性能。对于大多数简单的字符串包含检测需求，它是 PHP 8 及更高版本中的首选方法。

经典且强大的工具：strpos() 与 stripos()

在 `str_contains()` 出现之前，`strpos()` 及其不区分大小写的变体 `stripos()` 是 PHP 中最常用的字符串包含检测方法。它们通过查找子字符串首次出现的位置来判断包含关系。

strpos() - 区分大小写查找

`strpos(string $haystack, string $needle, int $offset = 0): int|false`

`$haystack`: 要搜索的主字符串。
`$needle`: 要查找的子字符串。
`$offset`: 可选参数，指定从 `$haystack` 的哪个位置开始搜索。默认从开头 (0) 搜索。
返回 `$needle` 在 `$haystack` 中首次出现的数字位置（从 0 开始），如果未找到则返回 `false`。
注意：由于子字符串可能出现在字符串的开头（位置 0），而 0 在布尔上下文中会被视为 `false`，因此在判断是否包含时，必须使用严格比较 `!== false`。

stripos() - 不区分大小写查找

`stripos(string $haystack, string $needle, int $offset = 0): int|false`

参数和返回值与 `strpos()` 相同。
主要区别在于它在查找时不区分字母大小写。

示例

<?php
$sentence = "The quick brown fox jumps over the lazy dog.";
$word1 = "fox";
$word2 = "cat";
$word3 = "THE"; // 大写
// strpos - 区分大小写
if (strpos($sentence, $word1) !== false) {
echo "'$sentence' 包含 '$word1'."; // 输出: 'The quick brown fox jumps over the lazy dog.' 包含 'fox'.
}
if (strpos($sentence, $word2) === false) {
echo "'$sentence' 不包含 '$word2'."; // 输出: 'The quick brown fox jumps over the lazy dog.' 不包含 'cat'.
}
// strpos - 区分大小写，找不到 'THE'
if (strpos($sentence, $word3) !== false) {
echo "'$sentence' 包含 '$word3'.";
} else {
echo "'$sentence' 不包含 '$word3' (区分大小写)."; // 输出: 'The quick brown fox jumps over the lazy dog.' 不包含 'THE' (区分大小写).
}
// stripos - 不区分大小写，能找到 'THE'
if (stripos($sentence, $word3) !== false) {
echo "'$sentence' 包含 '$word3' (不区分大小写)."; // 输出: 'The quick brown fox jumps over the lazy dog.' 包含 'THE' (不区分大小写).
}
// 示例：从特定位置开始搜索
$fullText = "Hello world, hello PHP!";
$needle = "hello";
// 第一次出现的位置 (不区分大小写)
$firstPos = stripos($fullText, $needle); // 0
echo "'hello' 第一次出现在位置: $firstPos"; // 输出: 'hello' 第一次出现在位置: 0
// 从第一次出现之后的位置开始搜索
$secondPos = stripos($fullText, $needle, $firstPos + strlen($needle)); // 13
echo "'hello' 第二次出现在位置: $secondPos"; // 输出: 'hello' 第二次出现在位置: 13
?>

应用场景

`strpos()` 和 `stripos()` 适用于 PHP 8.0 之前的版本，或当你不仅需要判断包含关系，还需要知道子字符串在主字符串中的具体位置时。对于需要不区分大小写检测的场景，`stripos()` 是理想选择。

获取子字符串或判断包含：strstr() 与 stristr()

`strstr()` 和 `stristr()` 函数不仅能检测字符串包含，还能返回主字符串中从匹配点开始到末尾的部分，这在某些解析或截取字符串的场景中非常有用。

strstr() - 区分大小写查找并返回子字符串

`strstr(string $haystack, string $needle, bool $before_needle = false): string|false`

`$haystack`: 要搜索的主字符串。
`$needle`: 要查找的子字符串。
`$before_needle`: 可选参数，PHP 5.3.0+ 支持。如果设置为 `true`，则返回 `$needle` 之前的部分。默认 `false`，返回 `$needle` 及其之后的部分。
返回从 `$needle` 首次出现的位置开始到 `$haystack` 结尾的部分，如果未找到则返回 `false`。

stristr() - 不区分大小写查找并返回子字符串

`stristr(string $haystack, string $needle, bool $before_needle = false): string|false`

参数和返回值与 `strstr()` 相同。
主要区别在于它在查找时不区分字母大小写。

示例

<?php
$email = "user@";
$domain = "@";
$name = "USER"; // 大写
// strstr - 获取域部分
$result1 = strstr($email, $domain);
if ($result1 !== false) {
echo "邮箱包含域 '$domain'。从匹配点开始是: '$result1'."; // 输出: 邮箱包含域 '@'。从匹配点开始是: '@'.
}
// strstr - 获取用户名部分 (使用 $before_needle)
$username = strstr($email, "@", true); // PHP 5.3.0+
if ($username !== false) {
echo "用户名是: '$username'."; // 输出: 用户名是: 'user'.
}
// stristr - 不区分大小写获取域部分
$email_upper = "ADMIN@";
$domain_lower = "@";
$result2 = stristr($email_upper, $domain_lower);
if ($result2 !== false) {
echo "'$email_upper' 包含 '$domain_lower' (不区分大小写)。从匹配点开始是: '$result2'."; // 输出: 'ADMIN@' 包含 '@' (不区分大小写)。从匹配点开始是: '@'.
}
// stristr - 检测是否包含 (简单判断)
$longText = "PHP is a popular general-purpose scripting language.";
if (stristr($longText, "scripting") !== false) {
echo "'$longText' 包含 'scripting' (不区分大小写)."; // 输出: 'PHP is a popular general-purpose scripting language.' 包含 'scripting' (不区分大小写).
}
?>

应用场景

当你需要根据子字符串的存在来截取或解析主字符串的特定部分时，`strstr()` 和 `stristr()` 提供了便利。如果仅仅是判断包含，并且使用的是 PHP 8+，`str_contains()` 更为推荐；如果是旧版本，`strpos()` / `stripos()` 更简洁。

终极灵活性：正则表达式 (preg_match())

当你的字符串包含检测需求变得复杂，涉及模式匹配、多个条件、边界限制等时，正则表达式就成为了不可替代的工具。PHP 的 `preg_match()` 函数是处理这类高级字符串匹配的核心。

preg_match() - 正则表达式匹配

`preg_match(string $pattern, string $subject, array &$matches = null, int $flags = 0, int $offset = 0): int|false`

`$pattern`: 要搜索的正则表达式模式。
`$subject`: 要搜索的主字符串。
`$matches`: 可选参数，一个数组，如果提供了，则会填充所有匹配项。
`$flags`: 可选参数，可以控制匹配行为（例如 `PREG_OFFSET_CAPTURE` 获取匹配项的偏移量）。
`$offset`: 可选参数，指定从 `$subject` 的哪个位置开始搜索。
返回 1 如果 `$pattern` 至少匹配一次，0 如果未匹配，`false` 如果发生错误。

正则表达式基础与 flags

模式通常用 `/` 分隔符包围，例如 `/pattern/`。
`i` (PCRE_CASELESS)：不区分大小写匹配。例如 `/word/i`。
`w`：匹配单词边界。例如 `/\bword\b/` 只匹配完整的 "word"，而不是 "keyword"。
`.`：匹配除换行符以外的任何单个字符。
`*`：匹配前面的元素零次或多次。
`+`：匹配前面的元素一次或多次。
`?`：匹配前面的元素零次或一次。
`[abc]`：匹配字符集合中的任何一个字符。
`[^abc]`：匹配不在字符集合中的任何一个字符。

示例

<?php
$logEntry = "[2023-10-26 14:30:00] ERROR: User '' failed login from IP 192.168.1.100.";
// 1. 简单字符串包含 (区分大小写)
if (preg_match('/ERROR/', $logEntry)) {
echo "日志条目包含 'ERROR'."; // 输出: 日志条目包含 'ERROR'.
}
// 2. 简单字符串包含 (不区分大小写)
if (preg_match('/error/i', $logEntry)) {
echo "日志条目包含 'error' (不区分大小写)."; // 输出: 日志条目包含 'error' (不区分大小写).
}
// 3. 匹配一个完整的单词 (使用 \b 单词边界)
if (preg_match('/\bUser\b/', $logEntry)) {
echo "日志条目包含完整的单词 'User'."; // 输出: 日志条目包含完整的单词 'User'.
}
$url = "/products/item-123?param=value";
// 4. 匹配 URL 是否包含 'products' 或 'services'
if (preg_match('/products|services/i', $url)) {
echo "URL 包含 'products' 或 'services'."; // 输出: URL 包含 'products' 或 'services'.
}
// 5. 匹配 IP 地址模式
$ipPattern = '/\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/';
if (preg_match($ipPattern, $logEntry, $matches)) {
echo "日志条目包含 IP 地址: " . $matches[0] . ""; // 输出: 日志条目包含 IP 地址: 192.168.1.100
} else {
echo "日志条目不包含 IP 地址.";
}
// 6. 匹配文件名，以 .jpg 或 .png 结尾
$filename1 = "";
$filename2 = "";
if (preg_match('/\. (jpg|png)$/i', $filename1)) {
echo "'$filename1' 是一个图片文件."; // 输出: '' 是一个图片文件.
}
if (!preg_match('/\. (jpg|png)$/i', $filename2)) {
echo "'$filename2' 不是一个图片文件."; // 输出: '' 不是一个图片文件.
}
?>

应用场景

当字符串匹配逻辑复杂到简单的函数无法满足时，`preg_match()` 和正则表达式是你的最佳选择。例如：

验证复杂的输入格式 (邮箱、电话号码、URL 等)。
从文本中提取特定模式的数据。
查找符合特定结构而不是固定子字符串的文本。
需要进行单词边界、行首/行尾匹配等高级操作。

然而，正则表达式的性能开销通常高于简单的字符串函数，且编写和调试更复杂。因此，对于简单的包含检测，应优先考虑 `str_contains()` 或 `strpos()`。

选择合适的方法：决策指南

面对多种选择，理解何时使用哪种方法至关重要。以下是一些指导原则：

简单布尔判断 (PHP 8+)：

如果你只需要知道一个字符串是否包含另一个子字符串，并且你的 PHP 版本是 8.0 或更高，那么 `str_contains()` 是最佳选择。它最简洁、最易读，并且通常是性能最好的。

简单布尔判断 (PHP < 8.0)：

如果你使用的是旧版 PHP，且只需要判断字符串是否包含子字符串：

区分大小写：使用 `strpos($haystack, $needle) !== false`。
不区分大小写：使用 `stripos($haystack, $needle) !== false`。

需要子字符串位置：

如果你除了判断包含，还需要知道子字符串在主字符串中首次出现的位置：

区分大小写：使用 `strpos($haystack, $needle)`。
不区分大小写：使用 `stripos($haystack, $needle)`。

需要从匹配点截取字符串：

如果你想获取主字符串中从子字符串匹配点开始到末尾的部分：

区分大小写：使用 `strstr($haystack, $needle)`。
不区分大小写：使用 `stristr($haystack, $needle)`。
如果需要匹配点之前的部分 (PHP 5.3+): 使用 `strstr($haystack, $needle, true)` 或 `stristr($haystack, $needle, true)`。

复杂模式匹配：

当你的查找条件涉及复杂的模式（如匹配特定格式、单词边界、可选字符、重复模式等），或者你需要从字符串中提取符合特定模式的数据时，正则表达式 (`preg_match()`) 是唯一且最强大的选择。但请记住，其性能开销通常高于简单字符串函数，应仅在必要时使用。

性能考量 (一般情况)

对于大多数字符串包含检测任务，性能差异在毫秒级别，对于普通 Web 应用来说，通常不是瓶颈。然而，在处理大量文本或执行数百万次字符串操作时，性能差异会变得显著。大致的性能排序（从快到慢）是：

`str_contains()` (PHP 8+)
`strpos()` / `stripos()`
`strstr()` / `stristr()`
`preg_match()` (正则表达式引擎的开销较大)

因此，始终优先使用最简单、最直接的函数来解决问题。

边缘情况与最佳实践

空字符串作为 Needle：

当 `$needle` 是空字符串 `""` 时，`str_contains()` 会返回 `true`。`strpos()` 和 `stripos()` 会返回 0（因为空字符串被认为在任何字符串的开头），`strstr()` 和 `stristr()` 返回 `$haystack` 本身。这些行为通常是符合预期的，但开发者应知晓。

严格比较：

在使用 `strpos()` 或 `stripos()` 时，务必使用严格比较 `!== false` 或 `=== 0` 来判断是否找到子字符串，因为位置 0 是一个有效的位置，但在非严格比较中会被视为 `false`。

多字节字符串：

上述函数都是字节安全的，但对于包含非 ASCII 字符（如中文、日文、韩文等）的多字节字符串，它们可能会产生非预期的结果。例如，一个中文字符可能被识别为多个字节。如果你的应用程序需要处理多字节字符串，应该使用 `mb_strpos()`、`mb_stripos()`、`mb_strstr()` 等 `mb_*` 系列函数，这些函数能够正确处理字符编码。

PHP 7 及以下版本的 `str_contains()` Polyfill：

如果你的项目需要兼容 PHP 8.0 以下的版本，但又希望使用 `str_contains()` 简洁的语法，你可以自行实现一个 polyfill：

<?php
if (!function_exists('str_contains')) {
function str_contains(string $haystack, string $needle): bool
{
return $needle === '' || strpos($haystack, $needle) !== false;
}
}
?>

将其包含在你的项目中，即可在旧版本 PHP 中使用 `str_contains()`。

PHP 提供了多种灵活且强大的方式来检测字符串是否包含子字符串。从 PHP 8+ 中简洁高效的 `str_contains()`，到经典实用的 `strpos()`/`stripos()`，再到功能强大的正则表达式 `preg_match()`，每种方法都有其独特的优势和适用场景。作为一名专业的程序员，理解这些工具的特点和局限性，并根据具体的业务需求、性能要求和 PHP 版本选择最合适的方案，是编写高质量、可维护代码的关键。始终记住，优先选择最简单、最易读且性能满足需求的方案，只有当需求复杂化时，才逐步升级到更强大的工具。
```

2025-11-24

上一篇：PHP数组读取深度解析：从基础到高级，掌握数据访问精髓

下一篇：PHP字符串操作：深入解析删除首个字符及子串的多种高效方法