PHP str_contains 传入空字符串为什么总是返回 true

我第一次把 str_contains() 放进搜索接口时，最容易忽略的情况不是关键字不存在，而是关键字根本没有内容。只要第二个参数是空字符串，PHP 就会返回 true。这不是 haystack 被“误搜”了，也不是函数随机失效，而是空字符串作为长度为 0 的序列，可以在目标字符串的边界位置匹配。

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

str_contains($haystack, $needle) 的判断重点是“是否包含 needle”。当 needle 为 '' 时，业务代码应先定义空关键字的含义，不能把返回的 true 直接当成有效搜索命中。

先把“返回 true”与“有命中内容”分开

这个现象通常出现在列表搜索、标签筛选或接口参数过滤中：调用方从查询参数读取 keyword，没有先判断它是否为空，就直接传给 str_contains()。如果当前记录是 订单-2026-华东，下面两次调用得到的布尔值可能一样，但业务含义完全不同。

因此，不能把 true 解释成“用户输入的词在订单标题中出现了”。它只回答了函数层面的包含关系，至于空输入应该展示全部数据、提示用户输入，还是视为没有筛选，需要由搜索接口自己决定。

空字符串为什么也能被看作“包含”

从字符串定义看，空字符串没有需要占用的字符，它的长度是 0。把一个长度为 0 的序列放到另一个字符串中，不需要消耗任何字符，所以在开头、任意两个字符之间以及结尾都能找到一个匹配位置。PHP 手册也明确提示，检查空字符串的存在会返回 true。

这和“搜索词不为空但没有出现”是两条不同路径：

我在排查这类问题时会先打印 needle 的长度，而不是只看布尔结果。这样可以快速确认是“搜索词不存在”，还是“搜索词在进入函数前已经变成空字符串”。

调用前要先处理空白和空字符串

用户输入常常不只是 ''：也可能是只包含空格、制表符或换行的字符串。是否把这些内容视为空关键字，要看产品对搜索框的约定。对普通文本搜索，我通常先做 trim()，再根据结果选择提示或默认结果；如果空格本身是有效数据，就不能无条件裁剪。

 false, 'message' => '请输入搜索关键字', 'items' => []];
}

// 到这里才把 true/false 作为有效的字符串包含结果处理。
$matched = str_contains($haystack, $keyword);

如果产品规则是“没有关键字就展示全部”，分支可以返回未过滤列表；如果规则是“必须输入关键字”，就应该返回提示。重要的是先把策略写在分支里，而不是让 str_contains() 的默认语义偷偷决定页面结果。

把搜索语义封装在一个小函数里

当多个控制器、命令行任务都要做关键字匹配时，建议把空值策略集中起来。下面的函数把“空关键字不执行筛选”表达为 null，把真正的命中与未命中保留为布尔值，调用方就不容易把三种状态混成一个 true/false。

这里的 null 不是为了增加复杂度，而是为了保留输入状态。对于一个搜索接口，至少有“没有筛选条件”“有条件且命中”“有条件但未命中”三种结果；把它们都压缩成布尔值，后续页面和统计很容易误判。

用边界样例复查调用方的含义

复查时不要只测一个正常关键字。至少准备空字符串、只有空白、命中和未命中四组输入，并明确每组应该进入哪条业务分支。下面的样例只演示判断顺序，不依赖本机执行结果。

复查重点是结果语义：空字符串和空白输入应该由产品规则处理，而不是被解释为“每条数据都命中”；只有经过归一化仍然有内容的关键字，才把 str_contains() 的布尔结果交给筛选器。

常见问题

str_contains($text, '') 能不能改成返回 false？

不要修改函数本身的语义。可以在调用前判断 $needle === ''，然后按业务要求返回提示、默认列表或一个明确的“没有筛选条件”状态。

只用 empty($keyword) 判断可以吗？

要谨慎。empty() 会把数字零、字符串 '0' 等值也视为 empty；如果搜索词 0 是有效输入，应使用更精确的字符串归一化和严格比较。

为什么不用 strpos() 代替？

strpos() 返回位置或 false，需要额外使用严格比较；str_contains() 直接返回布尔值，表达“是否包含”更清楚。无论使用哪一个，空输入的业务策略都应先写清楚。

trim() 是否总是正确？

不是。如果空格是领域数据的一部分，就不应自动裁剪。trim() 是普通搜索框的一个选择，真正的规则应由输入协议和业务场景决定。

这次排查最后留下的判断很简单：str_contains() 返回 true，只说明第二个参数作为字符串序列可以匹配；当这个序列为空时，应用必须自己决定它是不是一次有效搜索。先处理输入状态，再调用包含判断，结果才不会把“没有筛选条件”误写成“全部命中”。