PHP字符串包含判断：从基础函数到高级正则的全面指南与最佳实践126

在日常的编程任务中，字符串处理无疑是最常见且基础的操作之一。无论是用户输入验证、日志分析、URL路由、内容过滤还是数据解析，判断一个字符串是否包含另一个子字符串都是我们频繁遇到的需求。作为一名专业的PHP开发者，深入理解PHP中各种字符串包含检测的方法及其适用场景、性能考量和最佳实践，是提升代码质量和效率的关键。

本文将从PHP提供的基础函数入手，逐步深入到现代PHP特性以及强大的正则表达式，为您提供一个关于PHP字符串包含判断的全面指南。我们将详细探讨每种方法的原理、用法、优缺点，并通过丰富的代码示例帮助您巩固理解，最终形成一套适合不同场景的决策方案。

一、最直接的解决方案：PHP 8+ 的 `str_contains()`

随着PHP语言的不断演进，PHP 8.0引入了一个极其便捷且直观的函数：`str_contains()`。这个函数的设计目标就是为了解决“字符串是否包含子字符串”这个常见需求，提供了最简洁的布尔值结果。

1.1 `str_contains()` 的基本用法

`str_contains(string $haystack, string $needle): bool`
`$haystack`: 要检查的原始字符串（大海）。
`$needle`: 要搜索的子字符串（针）。
返回值：如果 `$haystack` 包含 `$needle`，则返回 `true`；否则返回 `false`。

示例代码：<?php
$fullString = "Hello, professional PHP developer!";
$subString1 = "PHP";
$subString2 = "Java";
$subString3 = "hello"; // 注意大小写敏感
// 示例 1：子字符串存在
if (str_contains($fullString, $subString1)) {
echo "'$fullString' 包含 '$subString1'."; // 输出: 'Hello, professional PHP developer!' 包含 'PHP'.
} else {
echo "'$fullString' 不包含 '$subString1'.";
}
// 示例 2：子字符串不存在
if (str_contains($fullString, $subString2)) {
echo "'$fullString' 包含 '$subString2'.";
} else {
echo "'$fullString' 不包含 '$subString2'."; // 输出: 'Hello, professional PHP developer!' 不包含 'Java'.
}
// 示例 3：大小写敏感性
if (str_contains($fullString, $subString3)) {
echo "'$fullString' 包含 '$subString3'.";
} else {
echo "'$fullString' 不包含 '$subString3'."; // 输出: 'Hello, professional PHP developer!' 不包含 'hello'.
}
// 示例 4：空字符串作为子字符串
if (str_contains($fullString, "")) {
echo "'$fullString' 包含空字符串 (始终为 true)."; // 输出: 'Hello, professional PHP developer!' 包含空字符串 (始终为 true).
}
?>

1.2 优点与缺点

优点：

极其简洁和直观： 直接返回布尔值，代码可读性极高。
性能优化： 底层实现经过优化，对于简单的包含检测，性能表现优秀。
现代化： 符合现代编程语言的设计趋势，是PHP 8+ 推荐的做法。


缺点：

PHP版本要求： 仅适用于PHP 8.0及更高版本。对于老旧项目，您需要考虑其他兼容性方案。
大小写敏感： 默认是大小写敏感的，如果需要不区分大小写，需要配合其他方法或预处理。

推荐： 如果您的项目运行在PHP 8.0或更高版本，`str_contains()` 应该是您判断字符串包含的首选方法。

二、PHP早期版本的经典方法：`strpos()` 和 `stripos()`

在 `str_contains()` 出现之前，`strpos()`（以及其不区分大小写的变体 `stripos()`）是PHP中实现字符串包含检测最常用的方法。虽然它们返回的是子字符串首次出现的位置，但通过巧妙的判断，也能实现包含检测。

2.1 `strpos()` 和 `stripos()` 的基本用法

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

`stripos(string $haystack, string $needle, int $offset = 0): int|false`
`$haystack`: 要检查的原始字符串。
`$needle`: 要搜索的子字符串。
`$offset`: 可选参数，指定从 `$haystack` 的哪个位置开始搜索。
返回值：如果找到子字符串，返回其首次出现的起始位置（整数）；如果未找到，则返回 `false`。

关键点： `strpos()` 返回 `0` 时表示子字符串在 `$haystack` 的开头被找到，而 `0` 在PHP的弱类型比较中会被认为是 `false`。因此，进行判断时必须使用严格比较运算符 `!== false` 或 `=== false`，以避免误判。

示例代码：<?php
$fullString = "Hello, world! PHP is great.";
$search1 = "world";
$search2 = "php";
$search3 = "World"; // 用于演示 stripos
// 示例 1: strpos - 找到子字符串 (非开头位置)
if (strpos($fullString, $search1) !== false) {
echo "'$fullString' 包含 '$search1' (strpos)."; // 输出: 'Hello, world! PHP is great.' 包含 'world' (strpos).
}
// 示例 2: strpos - 子字符串在开头
$startString = "PHP rules!";
$startSearch = "PHP";
if (strpos($startString, $startSearch) !== false) {
echo "'$startString' 包含 '$startSearch' (strpos, 位于开头)."; // 输出: 'PHP rules!' 包含 'PHP' (strpos, 位于开头).
}
// 错误示例：如果使用 `!= false`，当子字符串在开头时，`strpos()` 返回 0，`0 != false` 结果为 `true`，看似正确。
// 但如果未来修改了字符串或搜索词，使得子字符串不再开头，那么仍然需要 `!== false`，
// 养成使用 `!== false` 的习惯可以避免潜在的bug。
// 示例 3: strpos - 未找到子字符串
$notFoundSearch = "Python";
if (strpos($fullString, $notFoundSearch) === false) {
echo "'$fullString' 不包含 '$notFoundSearch' (strpos)."; // 输出: 'Hello, world! PHP is great.' 不包含 'Python' (strpos).
}
// 示例 4: stripos - 不区分大小写
if (stripos($fullString, $search3) !== false) {
echo "'$fullString' 包含 '$search3' (stripos, 不区分大小写)."; // 输出: 'Hello, world! PHP is great.' 包含 'World' (stripos, 不区分大小写).
}
// 示例 5: stripos - 不区分大小写找到小写
if (stripos($fullString, $search2) !== false) {
echo "'$fullString' 包含 '$search2' (stripos, 不区分大小写)."; // 输出: 'Hello, world! PHP is great.' 包含 'php' (stripos, 不区分大小写).
}
// 示例 6: 指定偏移量
$textWithDuplicates = "banana apple banana";
if (strpos($textWithDuplicates, "banana", 1) !== false) { // 从索引 1 开始搜索
echo "从索引 1 开始找到了 'banana'."; // 输出: 从索引 1 开始找到了 'banana'.
}
?>

2.2 优点与缺点

优点：

广泛兼容： 适用于几乎所有PHP版本，是老项目兼容性的首选。
性能良好： 对于简单字符串搜索，性能表现优秀。
提供位置信息： 不仅能判断是否存在，还能返回子字符串首次出现的位置，这在某些场景下非常有用。
区分大小写和不区分大小写： `strpos()` 和 `stripos()` 分别满足这两种需求。


缺点：

需要严格比较： 必须使用 `!== false` 或 `=== false` 进行判断，否则容易引入潜在的bug，降低代码健壮性。
代码略显冗余： 相较于 `str_contains()`，需要多写一个 `!== false`。

推荐： 对于PHP 8.0以下的版本，`strpos()` (或 `stripos()` 进行不区分大小写搜索) 配合严格比较是最佳实践。

三、获取匹配部分的旧方法：`strstr()` 和 `stristr()`

`strstr()` 和 `stristr()` 函数也常用于检查字符串包含，但它们的设计目的略有不同：它们不仅判断是否存在，还会返回子字符串（包括自身）及之后的部分。如果只需要判断是否存在，它们通常不是最高效的选择，但在需要获取匹配子串后续内容时，它们就非常有用。

3.1 `strstr()` 和 `stristr()` 的基本用法

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

`stristr(string $haystack, string $needle, bool $before_needle = false): string|false`
`$haystack`: 要检查的原始字符串。
`$needle`: 要搜索的子字符串。
`$before_needle`: 可选参数，如果设置为 `true`，则返回 `$needle` 之前的部分；默认 `false`，返回 `$needle` 及之后的部分。
返回值：如果找到子字符串，返回匹配到的部分（字符串）；如果未找到，则返回 `false`。

示例代码：<?php
$email = "user@";
$domainSeparator = "@";
// 示例 1: strstr - 获取域名部分
$domainPart = strstr($email, $domainSeparator);
if ($domainPart !== false) {
echo "Domain part: " . $domainPart . ""; // 输出: Domain part: @
}
// 示例 2: strstr - 获取用户名部分 (使用 $before_needle = true)
$userPart = strstr($email, $domainSeparator, true);
if ($userPart !== false) {
echo "User part: " . $userPart . ""; // 输出: User part: user
}
// 示例 3: stristr - 不区分大小写
$text = "My Website is ";
$searchDomain = "";
$found = stristr($text, $searchDomain);
if ($found !== false) {
echo "Found (case-insensitive): " . $found . ""; // 输出: Found (case-insensitive):
}
// 示例 4: 未找到
$notFound = "";
if (strstr($email, $notFound) === false) {
echo "'$email' 不包含 '$notFound'."; // 输出: 'user@' 不包含 ''.
}
?>

3.2 优点与缺点

优点：

获取匹配内容： 能够方便地截取字符串中从匹配点开始（或之前）的部分。
广泛兼容： 同样适用于几乎所有PHP版本。


缺点：

返回字符串而非布尔值： 如果仅仅需要判断是否存在，它的返回值类型不如 `str_contains()` 或 `strpos()` 直观，且可能造成额外的内存分配。
性能略逊： 对于纯粹的“包含判断”，它通常比 `strpos()` 效率稍低，因为还需要构建并返回子字符串。

推荐： 当您不仅需要判断子字符串是否存在，还需要获取包含子字符串在内的原始字符串的后续部分（或之前部分）时，`strstr()` 或 `stristr()` 是合适的选择。

四、强大而灵活的利器：正则表达式 `preg_match()`

当简单的字符串匹配无法满足需求时，正则表达式（Regular Expressions）就成了处理复杂模式匹配的终极武器。PHP提供了PCRE (Perl Compatible Regular Expressions) 扩展，其中的 `preg_match()` 函数可以轻松实现复杂的字符串包含检测。

4.1 `preg_match()` 的基本用法

`preg_match(string $pattern, string $subject, array &$matches = null, int $flags = 0, int $offset = 0): int|false`
`$pattern`: 要搜索的正则表达式模式。
`$subject`: 要检查的原始字符串。
`$matches`: 可选参数，用于存储所有匹配项的数组。
返回值：如果找到匹配项，则返回 `1`；未找到则返回 `0`；发生错误则返回 `false`。

示例代码：<?php
$fullString = "The quick brown fox jumps over the lazy dog. Version 2.0";
// 示例 1: 简单包含检测 (区分大小写)
if (preg_match('/fox/', $fullString)) {
echo "'$fullString' 包含 'fox' (正则)."; // 输出: 'The quick brown fox jumps over the lazy dog. Version 2.0' 包含 'fox' (正则).
}
// 示例 2: 不区分大小写匹配 (使用修饰符 i)
if (preg_match('/php/i', $fullString)) { // /i 表示不区分大小写
echo "'$fullString' 包含 'php' (不区分大小写正则).";
} else {
echo "'$fullString' 不包含 'php' (不区分大小写正则)."; // 输出: 'The quick brown fox jumps over the lazy dog. Version 2.0' 不包含 'php' (不区分大小写正则).
}
// 示例 3: 匹配多个可能的子字符串 (使用管道符 |)
if (preg_match('/fox|dog|cat/', $fullString)) {
echo "'$fullString' 包含 'fox', 'dog' 或 'cat' 中的一个."; // 输出: 'The quick brown fox jumps over the lazy dog. Version 2.0' 包含 'fox', 'dog' 或 'cat' 中的一个.
}
// 示例 4: 匹配特定模式，例如版本号
if (preg_match('/Version (\d+\.\d+)/', $fullString, $matches)) {
echo "找到版本号: " . $matches[1] . ""; // 输出: 找到版本号: 2.0
}
// 示例 5: 匹配单词边界
$text = "apple,pineapple,banana";
if (preg_match('/\bapple\b/', $text)) { // \b 代表单词边界
echo "'$text' 包含独立单词 'apple'."; // 输出: 'apple,pineapple,banana' 包含独立单词 'apple'.
} else {
echo "'$text' 不包含独立单词 'apple'.";
}
if (preg_match('/apple/', $text)) { // 没有单词边界，会匹配 pineapple 中的 apple
echo "'$text' 包含 'apple' (无单词边界)."; // 输出: 'apple,pineapple,banana' 包含 'apple' (无单词边界).
}
?>

4.2 优点与缺点

优点：

无与伦比的灵活性： 可以匹配任何复杂的模式，包括但不限于：数字、字母、特定字符集、单词边界、重复模式等。
强大的功能： 支持捕获组、前瞻、后顾等高级功能，能够实现非常精细的匹配和提取。
不区分大小写等修饰符： 通过修饰符（如 `i`），可以轻松控制匹配行为。


缺点：

学习曲线： 正则表达式语法相对复杂，需要一定的学习成本。
性能开销： 对于简单的子字符串包含检测，`preg_match()` 的性能通常低于 `str_contains()` 或 `strpos()`，因为正则表达式引擎需要进行额外的解析和匹配过程。
可读性： 复杂的正则表达式可能会降低代码的可读性。

推荐： 当需要进行复杂的模式匹配，或者简单的字符串函数无法满足需求时，`preg_match()` 是不可替代的选择。对于简单的字符串包含检测，应优先考虑 `str_contains()` 或 `strpos()`。

五、多字节字符串处理：`mb_strpos()` 和 `mb_stripos()`

当处理包含非ASCII字符（如中文、日文、韩文等）的多字节字符串时，标准的 `strpos()` 和 `stripos()` 可能会出现意外行为，因为它们默认是按字节处理字符串的。为了正确处理这些情况，PHP提供了多字节字符串函数（`mb_*` 系列函数）。

5.1 `mb_strpos()` 和 `mb_stripos()` 的基本用法

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

`mb_stripos(string $haystack, string $needle, int $offset = 0, ?string $encoding = null): int|false`
参数与 `strpos()` 类似，但增加了一个可选的 `$encoding` 参数，用于指定字符串的字符编码（默认为内部编码）。

示例代码：<?php
$multiByteString = "你好，世界！PHP编程";
$searchChinese = "世界";
$searchEnglish = "PHP";
// 示例 1: mb_strpos - 正常工作 (UTF-8编码)
if (mb_strpos($multiByteString, $searchChinese, 0, 'UTF-8') !== false) {
echo "'$multiByteString' 包含 '$searchChinese' (mb_strpos)."; // 输出: '你好，世界！PHP编程' 包含 '世界' (mb_strpos).
}
// 示例 2: mb_stripos - 不区分大小写 (对于中文通常不适用，但对于英文子串有用)
$text = "PHP编程很有趣，php是最好的语言。";
if (mb_stripos($text, "php", 0, 'UTF-8') !== false) {
echo "'$text' 包含 'php' (mb_stripos, 不区分大小写)."; // 输出: 'PHP编程很有趣，php是最好的语言。' 包含 'php' (mb_stripos, 不区分大小写).
}
// 警告：如果使用 strpos 处理多字节字符串，可能会得到错误结果
// $wrongPosition = strpos($multiByteString, $searchChinese);
// var_dump($wrongPosition); // 可能返回非预期的字节位置或 false，取决于字符集和子串。
?>

推荐： 当处理包含非ASCII字符的字符串时，始终使用 `mb_strpos()` 或 `mb_stripos()` 来确保正确性和健壮性。

六、性能考量与最佳实践

了解了各种方法后，如何选择最合适的一个至关重要。以下是一些性能考量和最佳实践的建议：

6.1 性能比较（大致优先级）：

`str_contains()` (PHP 8+)： 对于简单的布尔判断，它是最快、最清晰的选择。
`strpos()` / `stripos()`： 性能非常接近 `str_contains()`，特别是在PHP 7+版本中。对于PHP 8以下版本是首选。
`strstr()` / `stristr()`： 略慢于 `strpos()`，因为需要返回子字符串，而非仅仅判断位置。
`preg_match()`： 正则表达式引擎有其固有的开销，对于简单字符串包含，它是最慢的。但其灵活性无与伦比。
`mb_strpos()` / `mb_stripos()`： 通常比对应的单字节函数稍慢，因为需要处理多字节编码，但为了正确性，在处理多字节字符串时必须使用。

注意： 这种性能排序是在“简单字符串包含检测”场景下。如果任务本身就是复杂的模式匹配，那么 `preg_match()` 的效率可能会远高于尝试用 `strpos()` 组合实现复杂逻辑。

6.2 最佳实践：

优先使用 `str_contains()` (PHP 8+)： 如果项目允许，这是最推荐的做法，因为它简洁、直观、性能好。
使用 `strpos()` (配合 `!== false`) (PHP < 8)： 对于PHP 8以下的版本，这是判断字符串包含的最佳方法。务必使用严格比较。
利用 `stripos()` 进行不区分大小写匹配： 如果需要忽略大小写，`stripos()` 是比先转换为小写再用 `strpos()` 更高效的方式。
`preg_match()` 留给复杂模式： 只有当需要匹配复杂的、非固定子字符串的模式时，才考虑使用正则表达式。对于简单包含，避免过度使用正则。
多字节字符串使用 `mb_*` 函数： 如果您的应用可能处理包含中文、日文等字符的字符串，请务必使用 `mb_strpos()` 等 `mb_*` 系列函数，并指定正确的编码，以避免字符计算错误。
避免在循环中重复计算： 如果在一个大数据量的循环中进行字符串包含检测，并且子字符串不变，可以考虑将子字符串或模式预处理，或使用更高效的数据结构。

七、实际应用场景

字符串包含判断在Web开发中无处不在：
表单验证： 检查用户输入是否包含敏感词、特定格式（如URL是否包含``）。
URL路由： 判断请求URL是否匹配某个路由规则（如 `/api/v1/users/` ）。
日志分析： 在日志文件中搜索特定错误信息或关键词。
内容过滤： 过滤用户发布内容中的广告词、非法词汇。
代码高亮/编辑器： 判断文本中是否包含特定关键字进行高亮。
模板引擎： 检查模板变量中是否包含特定数据。

八、总结

PHP提供了多种强大的函数来检查字符串里是否包含另一个子字符串。从PHP 8+ 简洁直观的 `str_contains()`，到适用于所有PHP版本且高效的 `strpos()`/`stripos()`，再到处理复杂模式的利器 `preg_match()`，以及应对多字节字符的 `mb_strpos()`。每种方法都有其独特的适用场景和优缺点。

作为专业的程序员，我们应该根据实际需求、项目兼容性（PHP版本）、性能要求以及匹配的复杂程度，明智地选择最合适的工具。在大多数情况下，对于简单的包含检测，`str_contains()`（PHP 8+）或 `strpos()`（PHP < 8）是您的首选。而当您的匹配需求变得复杂时，`preg_match()` 则会成为您的得力助手。理解并灵活运用这些函数，将使您的PHP代码更加健壮、高效和易于维护。

2025-11-02

---

上一篇：PHP数组精通指南：从基础到高级的视频教程与实战详解

下一篇：PHP后端数据与前端交互：从数据库到用户界面的完整旅程