科技行业

PHP 8.6:新功能、已弃用函数以及实用迁移指南

PHP 8.6: New Features, Deprecated Functions, and a Practical Migration Guide

升级到 PHP 8.6,附带已弃用 PHP 函数、MySQLi、mbstring、CSV、会话的前后对比示例,以及实用的迁移清单。

PHP 8.6.0 于 2026 年 11 月 19 日发布。其头条功能很有趣,但对于维护真实网站的开发人员来说,最紧迫的问题通常不同:现有代码的哪些行将开始发出弃用通知,以及应该如何重写?

本指南将迁移工作放在首位。每个示例都会识别一个弃用的 API,展示替代方案,并指出机械化搜索替换会在哪些地方带来危险。弃用通知不等同于即时致命错误:它警告代码需要关注,通常在未来的大版本移除该 API 之前发出警告。

PHP 8.6 迁移路径:清单、暂存、日志、修复和回归测试

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);
Illustration of the article's main concept

修改后 — 替换:

<?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
    }
}

修改后 — 保留清理而不覆盖结果:

Technical workflow illustration
<?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 8.6 迁移工作流

可复现的迁移序列

  1. 记录当前 PHP 版本和已启用的扩展。
  2. 备份文件和数据库;准备暂存副本。
  3. 在启用弃用日志的情况下,在 PHP 8.6 下运行项目。
  4. 按文件和行清点警告,再按 API 分组。
  5. 先用针对性修改修复第一方代码;单独更新第三方依赖。
  6. 重新运行单元/集成测试和重要用户旅程。
  7. 检查表单、登录、会话、邮件、支付、计划任务、CSV 导入/导出和数据库访问。
  8. 带着回滚计划部署;发布后监控错误日志。

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、会话和区域设置敏感操作。

官方来源