PHP str_contains 处理空字符串时怎样理解结果

PHP 的 str_contains($haystack, $needle) 在 $needle 是空字符串时返回 true，这是函数定义的一部分，不是异常结果；同时它是大小写敏感的。真正容易出错的地方，是把“空查询词”误当成“已经找到有效关键词”，然后让过滤条件意外放行全部数据。

官方地址：https://www.php.net/manual/en/function.str-contains.php

先把空输入的业务含义单独定下来，再调用 str_contains。如果空字符串代表“没有筛选条件”，返回 true 合理；如果它代表“缺少必填关键词”，就应该在调用前拒绝，而不是依赖函数返回值。

我先把空字符串和未命中分开看

我第一次遇到这个边界时，代码看上去很直观：拿标题和用户输入调用 str_contains。问题在于，用户输入可能是经过 trim 后的空字符串。此时函数并不是在说“标题里存在一个有内容的词”，而是在判断一个长度为零的子串是否位于字符串中。PHP 手册明确给出的行为是：检查空字符串的存在始终返回 true。

因此，下面两件事要分成两层：字符串函数只负责字面包含关系；业务代码负责决定空搜索词是否应该跳过过滤、返回空结果，或者直接报参数错误。

最小案例能看清四个结果

把空 needle、大小写变化和普通命中放在同一个数组里，比只看一个 true 更容易排查问题。下面的注释说明每组案例的边界，示例使用 PHP 8 的原生函数。

 ['PHP guide', ''],
    'exact_case' => ['PHP guide', 'guide'],
    'different_case' => ['PHP guide', 'Guide'],
    'not_found' => ['PHP guide', 'Go'],
];

foreach ($cases as $name => [$haystack, $needle]) {
    // 显式输出 true/false，避免布尔值被当成空字符串或数字误读。
    $matched = str_contains($haystack, $needle);
    echo $name, ': ', $matched ? 'true' : 'false', PHP_EOL;
}

按函数语义推导，empty_needle 和 exact_case 为 true，different_case 与 not_found 为 false。函数本身不会忽略大小写，也不会替你做多字节大小写折叠。

大小写不一致时不要把问题归因给空字符串

str_contains 只进行大小写敏感检查。比如标题里有 PHP，needle 写成 php，即使两个词在自然语言里看起来相同，函数也会返回 false。这个边界和空 needle 是两种独立情况：前者是字符大小写不匹配，后者是 needle 根本没有字符。

如果业务确实要求忽略大小写，可以在明确编码和语言范围后统一转换，再比较；不要只把一侧转换。对于 ASCII 标识符，使用 strtolower 后再调用通常足够。对用户可见的非 ASCII 文本，应先确认项目的大小写规则，必要时采用合适的多字节处理方式。

用户输入为空时，先写出业务决策

搜索框、标签过滤器和接口参数最容易把这个边界放大。假设 keyword 来自请求参数，直接写 str_contains($title, trim($keyword))，空输入就会让每条标题通过。它可能是正确的“不过滤”，也可能是错误的“校验绕过”，区别不在 PHP 函数，而在产品约定。

我通常把分支写在调用前，让后续维护者一眼看到空输入的决定：

如果接口的关键词是必填项，分支可以返回参数错误；如果它是可选筛选条件，返回 true 表示不增加过滤条件。无论采用哪种策略，都不要用“先调用再猜返回值”的方式表达业务规则。

PHP 7 兼容时要保留空 needle 规则

str_contains 是 PHP 8 提供的函数。需要支持更早版本时，可以把兼容函数放在项目命名空间或统一工具层，并明确空 needle 的返回值。常见的 strpos 写法还要使用严格比较，因为位置 0 不能和 false 混淆。

兼容层解决的是函数可用性，不会自动解决大小写、编码或业务校验。升级到 PHP 8 后，可以逐步替换为原生函数，但仍建议保留调用前的空输入分支。

用一张表复查调用边界

我现在处理这类问题时，会先问一句“空输入在这个接口里是什么意思”。如果答案是“不过滤”，可以保留 true 语义；如果答案是“参数无效”，就在调用前返回错误。这样既不误解 str_contains，也不会让一个看似普通的字符串判断承担业务校验职责。

str_contains 能不能自动忽略大小写？

不能。它是大小写敏感检查，需要由业务代码选择统一转换或其他合适的比较方案。

为什么空字符串返回 true？

因为函数检查的是 needle 是否作为子串存在，零长度字符串在任意字符串中都满足这个包含关系。工程上仍应单独决定空输入是否有效。

PHP 7 能直接调用 str_contains 吗？

不能依赖原生函数。可以使用项目级兼容函数，并用严格的 !== false 判断 strpos 的结果。