PHP扩展兼容矩阵在升级前的验收方法

PHP升级前最容易漏掉的不是语法变化，而是“代码能装上、运行时却缺扩展”这一层。比较稳妥的做法是把验收拆成四个维度：目标PHP运行时、实际加载的扩展、Composer锁定依赖、框架关键业务回归。每一格都留下命令输出或测试结果，升级是否可行就不再靠“看起来能启动”判断。

官方入口：https://www.php.net/supported-versions.php　Composer文档：https://getcomposer.org/doc/03-cli.md#check-platform-reqs

先把升级对象拆成四层

“PHP 8.x兼容”不是一个足够细的结论。同一份代码在CLI、FPM和队列消费者里可能加载不同的php.ini；同一个扩展也可能在开发机存在、容器镜像里缺失。建议先建一张小矩阵：

矩阵的价值在于把“装不上”和“装上但行为变了”分开。前者通常由平台约束直接解释，后者要交给回归用例和日志判断。

用运行时命令建立可比较的基线

先在当前环境保存基线，再在候选环境执行同一组命令。PHP手册说明，extension_loaded()用于判断某扩展是否已加载，get_loaded_extensions()则返回已编译并加载的模块名。

# 记录运行时、SAPI和配置文件，便于比较两台机器
php -v
php --ini
php -r 'echo PHP_SAPI, "\n", PHP_OS_FAMILY, "\n";'

# 输出当前进程真正加载的扩展，避免只看镜像构建脚本
php -m | sort

# 用应用关心的扩展做快速阻断检查
php -r '$required = ["mbstring", "pdo_mysql", "intl"]; foreach ($required as $name) { if (!extension_loaded($name)) { fwrite(STDERR, "缺少扩展: $name\n"); exit(1); } } echo "扩展基线通过\n";'

这组命令只说明CLI进程的状态。如果生产请求由FPM处理，还要在与FPM相同的镜像和配置下重复采集；不要拿开发机的php -m结果替代生产候选环境的证据。

用Composer检查真实平台，而不是只看模拟版本

Composer官方把PHP和扩展视为平台要求。composer check-platform-reqs会检查已安装包需要的PHP及扩展版本，并且会忽略config.platform，直接检查真实平台。这一点很关键：config.platform可以帮助解析依赖，但不能证明服务器真的装有对应扩展。

# 依据锁定依赖检查真实PHP与扩展，失败时保留完整输出
composer check-platform-reqs --lock --no-dev

# 生成机器可读结果，供CI归档和矩阵标记使用
composer check-platform-reqs --lock --no-dev --format=json > build/platform-check.json

# 安装阶段不要用忽略平台参数掩盖缺失扩展
# composer install --ignore-platform-reqs 只能让安装继续，不能修复运行时环境

如果项目在composer.json中声明了ext-intl，但候选镜像没有加载它，矩阵应标记为阻塞，而不是删掉约束。只有确认代码不再使用该扩展，才应通过依赖变更和回归测试正式移除。

把扩展验收和业务回归分开

扩展检查通过后，再运行框架和业务测试。优先覆盖容易受原生扩展影响的路径：数据库连接与事务、JSON或多字节文本、图片处理、时区与国际化、文件上传、队列消费者。每一项记录“输入、预期、实际、日志关键词”，不要只保存一个总的成功状态。

# 先执行单元测试，再执行少量高价值集成用例
vendor/bin/phpunit --testsuite unit
vendor/bin/phpunit --testsuite critical

# 把候选环境的错误和警告单独归档，便于与基线比较
php -d display_errors=1 bin/console app:health-check 2> build/runtime-errors.log

例如数据库扩展加载成功，只能说明连接能力存在；它不能证明字符集、事务隔离或连接池配置符合业务要求。测试结果与扩展清单必须同时为绿，才算这一层通过。

灰度切换前的验收清单

• 候选环境的PHP版本、SAPI、架构和php.ini来源已记录。
• 所有ext-*要求都通过真实平台检查，未使用忽略参数掩盖问题。
• CLI、FPM和队列消费者分别完成扩展采集。
• 关键路径测试通过，错误日志没有新增未解释的警告。
• 保留旧镜像、数据库兼容策略和一键回滚入口。

PHP官方支持页会持续更新分支的支持状态，因此矩阵里的“目标版本”不能永久写死；每次升级评审都应重新核对官方支持范围，再结合项目依赖决定是否进入灰度。

常见问题

为什么本地能运行，CI却提示缺少扩展？

通常是CLI环境、容器镜像或php.ini不同。先比较php --ini和php -m，再跑真实平台检查。

把config.platform改成目标版本就够了吗？

不够。它主要影响依赖解析；服务器是否真的具备PHP版本和扩展，仍要由composer check-platform-reqs与业务测试确认。

扩展检查通过后为什么还要做上传和队列回归？

扩展只代表底层能力已加载，文件权限、序列化格式、连接参数和异步消费链路仍可能在升级中发生行为差异。