PHP 8.6:新功能、已弃用函数以及实用迁移指南
升级到 PHP 8.6,附带已弃用 PHP 函数、MySQLi、mbstring、CSV、会话的前后对比示例,以及实用的迁移清单。
PHP 8.6.0 于 2026 年 11 月 19 日发布。其头条功能很有趣,但对于维护真实网站的开发人员来说,最紧迫的问题通常不同:现有代码的哪些行将开始发出弃用通知,以及应该如何重写?
本指南将迁移工作放在首位。每个示例都会识别一个弃用的 API,展示替代方案,并指出机械化搜索替换会在哪些地方带来危险。弃用通知不等同于即时致命错误:它警告代码需要关注,通常在未来的大版本移除该 API 之前发出警告。
1. 动手生产环境前先检查运行时
在为应用提供服务的同一 PHP 环境中运行以下命令(CLI 和 Web PHP 可能使用不同的二进制文件和设置):
php -v
php -m
php --ini
检查项目使用的扩展,特别是 mbstring、mysqli 和 intl。验证框架、CMS、扩展和托管环境明确支持 PHP 8.6;不要仅因为网站能启动就推断兼容性。
在暂存环境中,记录所有错误,同时将诊断消息排除在公共 HTML 之外:
<?php
error_reporting(E_ALL);
ini_set('log_errors', '1');
ini_set('display_errors', '0');
这些运行时设置适用于受控测试。对于长期运行的环境,建议在服务器层面配置日志记录;确保错误日志可写且为私有。即使页面仍能渲染,Deprecated 消息也是可操作的。
2. 快速参考:弃用的 API 及其替代方案
| PHP 8.6 中弃用 | 推荐方法 | 迁移注意事项 |
|---|---|---|
is_integer(), is_long() |
is_int() |
直接别名 |
is_double() |
is_float() |
直接别名 |
doubleval() |
floatval() |
直接别名 |
spl_object_hash() |
spl_object_id() |
返回类型从 string 变为 int |
mb_ereg(), mb_eregi() |
preg_match() |
调整模式语法和 Unicode 标志 |
mb_ereg_replace() |
preg_replace() |
检查转义、替换语义和错误 |
mysqli_stmt_init() |
mysqli_prepare() |
立即准备 |
mysqli_get_charset() |
mysqli_character_set_name() |
仅当需要字符集名称时 |
SplFileObject::fgetcsv() |
流上的 fgetcsv() |
重新审视流位置和 CSV 设置 |
SplFileObject::fputcsv() |
流上的 fputcsv() |
显式传递分隔符、包围符和转义符 |
strcoll() |
Collator::compare() |
需要 intl;选择一个区域设置 |
SORT_LOCALE_STRING |
Collator::sort() / asort() |
区域设置行为可能变化 |
spl_classes() |
ReflectionExtension::getClassNames() |
检查相应的扩展 |
define() 的第三个参数 |
省略该参数 | 旧的大小写不敏感模式已移除 |
finally 中的 return |
在 finally 外部返回 |
避免抑制异常 |
传递给 array_walk() 的对象 |
先使用 get_object_vars() |
按引用编辑可能不再改变对象 |
metaphone() |
维护中的音标实现 | 核心中无直接替代 |
某些 API 没有确切的替代品。正确的迁移可能需要更改设计,而不仅仅是重命名函数。请参阅 PHP 8.6 官方弃用列表。
3. 简单别名:安全、快速的修复
修改前 — 已弃用:
<?php
if (is_integer($quantity) && is_double($price)) {
$total = doubleval($price) * $quantity;
}
修改后:
<?php
if (is_int($quantity) && is_float($price)) {
$total = floatval($price) * $quantity;
}
这些别名具有相同的语义。不要假设 is_float(40) 为真:整数仍然是整数。该行为在迁移前就已存在。
对于字符串金额,floatval() 是一种转换,并非 金额安全的十进制表示。保持项目现有的金额处理策略,不要在无关的 PHP 升级过程中更改它。
4. 迁移 mbstring 正则表达式
mb_ereg* 系列被弃用,因为其底层的 Oniguruma 正则引擎不再维护。PHP 推荐许多用例使用 PCRE,但模式方言并不完全相同。
修改前:
<?php
$isReference = mb_ereg('^[0-9]+$', $reference) !== false;
修改后(仅 ASCII 数字):
<?php
$isReference = preg_match('/^[0-9]+$/D', $reference) === 1;
此处 D 修饰符使 $ 仅在目标字符串末尾匹配。对于 Unicode 文本,请使用适当的 UTF-8 模式和 u 修饰符:
<?php
$isName = preg_match('/^\p{L}+(?:[ -]\p{L}+)*$/uD', $name) === 1;
修改前 — 替换:
<?php
$clean = mb_ereg_replace('[[:space:]]+', ' ', $text);

修改后 — 替换:
<?php
$clean = preg_replace('/\s+/u', ' ', $text);
if ($clean === null) {
throw new RuntimeException('Regular expression failed');
}
这两个模式在某些 Unicode 空白字符上可能表现不同。对于真实迁移,请使用实际项目数据测试带重音字符、换行符、无效 UTF-8、捕获组和反向引用。不要在未审查表达式的情况下批量替换每个 mb_ereg 调用。
5. MySQLi:一步准备语句
修改前 — 已弃用:
<?php
$stmt = mysqli_stmt_init($mysqli);
mysqli_stmt_prepare($stmt, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
修改后:
<?php
$stmt = mysqli_prepare($mysqli, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
使用面向对象 API 时,请使用 $mysqli->prepare($sql) 代替 $mysqli->stmt_init() 后跟 prepare()。保留现有的错误处理并适当关闭语句。
单独的 mysqli_get_charset() API 也已弃用。如果你只需要当前字符集名称:
<?php
$charsetName = mysqli_character_set_name($mysqli);
这不是旧字符集信息对象所有字段的替代品。如果代码依赖排序规则元数据,请检查实际需要什么并适当查询服务器。
6. CSV:替换已弃用的 SplFileObject CSV 方法
SplFileObject 上特定于 CSV 的方法已弃用。对于新代码和迁移代码,请使用基于流的 fgetcsv() 和 fputcsv() 函数。
修改前:
<?php
$file = new SplFileObject($path, 'r');
while (!$file->eof()) {
$row = $file->fgetcsv();
// Process row
}
修改后:
<?php
$handle = fopen($path, 'rb');
if ($handle === false) {
throw new RuntimeException('Cannot open CSV file');
}
try {
while (($row = fgetcsv($handle, 0, ',', '"', '')) !== false) {
// Process row
}
} finally {
fclose($handle);
}
空的转义参数会禁用 PHP 专有的转义机制;请根据源系统导出的格式测试此选择。检查空行、标题、分隔符、嵌入换行符和编码。此例演示 API 变更,并非通用 CSV 解析器。
写入时,使用 fputcsv($handle, $fields, ',', '"', '')。保留原文件预期的方言。
7. 对象标识:spl_object_hash() 不是内容哈希
修改前:
<?php
$key = spl_object_hash($object);
修改后:
<?php
$key = spl_object_id($object);
替代函数返回整数,而非字符串。如果键被序列化、存储在数据库或通过 API 暴露,请先审查消费者。这两个函数都不产生跨请求持久的标识符,且对象销毁后 ID 可能被复用。对于以活对象标识为键的映射,请根据生命周期要求考虑 SplObjectStorage 或 WeakMap。
8. finally 中的 return 可能隐藏失败
修改前 — 已弃用且具有误导性:
<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
return []; // Overrides the result and hides exceptions
}
}
修改后 — 保留清理而不覆盖结果:

<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
releaseTemporaryResources();
}
}
如果原代码有意返回后备值,请将该决定移入带有显式处理的 catch 块中。不要无声地吞没本应到达调用者的异常。
9. 区域设置敏感的排序及其他不明显的变更
strcoll() 和 SORT_LOCALE_STRING 排序标志已弃用。推荐的 intl 替代方案是 Collator:
<?php
$collator = new Collator('fr_FR');
$names = ['Émile', 'Alice', 'Zoé'];
$collator->sort($names);
检查 intl 是否已安装。区域设置感知排序是业务规则:请测试预期顺序,而非假设 ICU 和进程全局区域设置始终表现相同。
其他迁移项目值得明确关注:
ArrayIterator: 排序、标志和序列化方法(如asort()、ksort()、setFlags()和serialize())已弃用。对底层数组排序或在 API 合适时使用ArrayObject;不要假设迭代器和容器可互换。- 自定义会话处理器: 按更新后的接口/行为要求实现
create_sid()和validateId()。PHP 8.6 启用更严格的会话默认值;测试登录、会话轮换和持久化。 __debugInfo(): 使用非空的array返回类型;返回null已弃用。define(): 移除第三个case_insensitive参数,即使它是false。http_build_query()和array_walk(): 在期望数组的地方传递对象已弃用。使用get_object_vars()有意转换或显式构造所需数组。metaphone(): 无等效的内置 PHP 替代品。选择并测试一个维护中、适合语言的音标算法。- 保留标识符:
let、is、readonly(函数)和namespace(类常量)等名称有新的弃用限制。谨慎重命名受影响的声明。 - 反射: 检查传递给
ReflectionProperty::setValue()的无效对象,以及调用静态方法时提供的对象参数。
请参阅 完整迁移指南 了解本实用精选未涵盖的边缘情况。
10. 在现有项目中查找弃用调用
从只读清单开始。在 Linux 或 macOS 上:
grep -RnE --include='*.php' \
'is_integer\(|is_long\(|is_double\(|doubleval\(|spl_object_hash\(|mb_ereg\(|mb_ereg_replace\(|mysqli_stmt_init\(|mysqli_get_charset\(' \
./src
将 ./src 替换为实际目录。此文本搜索可能匹配注释或字符串,且会遗漏动态调用、命名空间别名和其他弃用 API。它只是起点,而非完整的静态分析器。
对于跨平台选项,编辑器的“在文件中查找”可搜索相同名称。不要直接编辑 vendor 或 CMS 核心文件:更新上游包或向其维护者提交补丁。
可复现的迁移序列
- 记录当前 PHP 版本和已启用的扩展。
- 备份文件和数据库;准备暂存副本。
- 在启用弃用日志的情况下,在 PHP 8.6 下运行项目。
- 按文件和行清点警告,再按 API 分组。
- 先用针对性修改修复第一方代码;单独更新第三方依赖。
- 重新运行单元/集成测试和重要用户旅程。
- 检查表单、登录、会话、邮件、支付、计划任务、CSV 导入/导出和数据库访问。
- 带着回滚计划部署;发布后监控错误日志。
Joomla 和 WordPress: PHP 8.6 发布不代表每个 CMS 版本、扩展或插件都支持它。确认正在使用的确切版本的兼容性,并先测试暂存环境。不要将升级作为直接修补核心或 vendor 代码的理由。
11. PHP 8.6 实际上有哪些新特性?
除了弃用,该版本还增加了多项语言和运行时特性:
| 特性 | 实际用途 |
|---|---|
| 部分函数应用 | 预填参数并为剩余参数获得可调用对象 |
clamp() |
将值约束在最小值和最大值之间 |
\Time\Duration |
表示经过的时间而非日历日期 |
SortDirection |
通过标准枚举表示升序/降序方向 |
Io\Poll |
支持事件循环和 I/O 库中的流轮询 |
| readonly 属性的默认值 | 简化选定的不可变类声明 |
一个小而立竿见影的例子是 clamp():
<?php
// Before PHP 8.6
$percentage = min(100, max(0, $input));
// PHP 8.6
$percentage = clamp($input, 0, 100);
代码更易读,但迁移优先级仍应是兼容性测试。其他特性并非仅为让现有应用保持工作所必需。请参阅 官方发布公告。
12. 切换生产环境 PHP 版本前
将 PHP 8.6 视为受控升级,而非在繁忙生产服务器上点击的按钮。合理的发布清单包括:受支持的 CMS 和依赖;可用的扩展;无意外的弃用洪水;测试通过;已验证的数据库和会话行为;测试过的备份;以及回滚程序。
底线: PHP 8.6 带来有用的特性,但其弃用往往是维护工作的起点。先修复简单的别名,然后针对真实数据测试行为迁移——尤其是正则、CSV、会话和区域设置敏感操作。