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免费学习笔记（深入）”；
- 安全写法（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 或对象——这些在强类型上下文中可能隐式转成空字符串，逻辑就变了。
