17370845950

str_contains自PHP 8.0.0起引入，并非PHP 8.4新特性；它严格要求参数为字符串，区分大小写，空字符串恒为true，旧版本需用stripos !== false替代。

PHP 8.4 并没有 str_contains 函数——它早在 PHP 8.0 就已引入，且是原生函数，不是新特性。如果你在 PHP 8.4 环境下调用失败，大概率是因为版本实际低于 8.0，或启用了严格模式但传入了非字符串参数。

为什么 str_contains 会报 “undefined function”？

这是最常踩的坑：误以为它是 PHP 8.4 新增，结果在旧环境（如 7.4 或未升级的 8.0-）直接使用，导致致命错误。

• ✅ 正确前提：str_contains 自 PHP 8.0.0 起可用，无需额外扩展
• ❌ 常见误判：本地开发环境显示 PHP 8.4，但 CLI 和 Web Server（如 Apache mod_php）用的是不同版本，php -v 和 phpinfo() 结果不一致
• ❌ 参数类型错误：第二个参数 $needle 必须是 string，传 null、int 或 array 会触发 TypeError

str_contains 的基本用法和参数细节

它只做一件事：判断一个字符串是否包含另一个子串，返回 bool。没有大小写选项，不支持正则，也不修改原始字符串。

• 函数签名：str_contains(string $haystack, string $needle): bool
• $haystack 和 $needle 都会被强制转为字符串（但仅当类型兼容；array 会直接报错）
• 空字符串 '' 被认为包含在任何字符串中（包括空字符串本身）：str_contains('abc', '') === true
• 区分大小写：str_contains('Hello', 'hello') === false

var_dump(str_contains('filename.php', '.php')); // true
var_dump(str_contains('user@example.com', '@')); // true
var_dump(str_contains('test', '')); // true
var_dump(str_contains('TEST', 't')); // false

替代方案：PHP 7.x 或需要忽略大小写的场景

如果确实不能升级到 PHP 8.0+，或需要大小写不敏感匹配，不要用 stripos !== false 手动封装——容易漏掉 0 的边界情况。

• 安全写法（PHP 7.0+）：stripos($haystack, $needle) !== false
• 更健壮的封装（可复用）：

  function str_contains_ci(string $haystack, string $needle): bool {
      return stripos($haystack, $needle) !== false;
  }

• 注意：strpos/stripos 返回 int|false，必须用严格比较 !==，否则 strpos('abc', 'a') === 0 会被误判为 false

性能与编码注意事项

虽然 str_contains 是底层 C 实现，比 stripos 略快，但差异微乎其微。真正影响性能的是滥用或嵌套调用。

• 避免在循环内反复对同一长字符串调用多个 str_contains，考虑提前提取或用 str_split + in_array 预处理
• 如果 $needle 来自用户输入，确保已过滤或验证——该函数不做任何转义或清理
• UTF-8 多字节字符正常支持（如中文、emoji），但前提是源字符串编码正确；若字符串是 GBK 编码，str_contains 可能因字节截断误判

真正容易被忽略的点：它不处理 null。哪怕你写了 str_contains($filename ?? '', '.php')，也得确认 $filename 不是 0、false 或对象——这些在强类型上下文中可能隐式转成空字符串，逻辑就变了。