接手一个 2012 年开始的项目,代码里到处是 array()、mysql_query()、each()、create_function()。服务器还是 PHP 7.4,官方已经不维护了,必须升到 8.3。在测试环境切过去,第一屏就 500:Call to undefined function each()。改掉这一处,下一处又冒出来;一天下来,光「函数不存在」就修了十几个。

这就是老项目升级的真实节奏:不是学几个新语法,而是先清理已经不能用的东西,再逐步把代码写成现代风格。这篇先列一份「必须改」的清单,再讲 PHP 8 里值得用的写法,最后用一个订单模块走一遍从旧到新的改造,以及升级上线该怎么控制风险。

先清理:这些写法已经不能用

PHP 8 不是「加了几个函数」的小版本,它在 7.x 到 8.x 之间删掉了一批历史 API。下面这些在老代码里很常见,遇到就得改:

旧写法状态替代
mysql_* 系列PHP 7.0 起移除PDO 或 mysqli,用预处理
each()PHP 8.0 移除foreach ($arr as $k => $v)
create_function()PHP 8.0 移除闭包或箭头函数
money_format()PHP 8.0 移除NumberFormatter 或 number_format()
ereg_* / split()PHP 7.0 移除preg_* / explode()
$HTTP_RAW_POST_DATAPHP 7.0 移除file_get_contents('php://input')
get_magic_quotes_gpc()PHP 8.0 移除删除相关判断,参数自己转义
"${var}" 插值PHP 8.2 废弃"{$var}"
utf8_encode() / utf8_decode()PHP 8.2 废弃mb_convert_encoding()
给未声明的属性赋值PHP 8.2 废弃在类里声明属性

清理顺序建议从「会直接 fatal」的开始:移除的函数和类。然后是「只报 Deprecated」的,比如动态属性、废弃函数,它们不会立刻挂,但会在日志里刷屏,并且在下一个大版本变成 fatal。最后才是语法风格的现代化。

工具能省不少事。PHPCompatibility 这类静态检查可以按目标版本扫出问题;框架和依赖的版本也要先升到支持 PHP 8 的版本,否则你自己的代码改完了,框架先崩。

还有一类改动不报「函数不存在」,但行为会变,升级时最容易漏。它们不一定 500,可能只是结果不对:

  • 动态属性:PHP 8.2 起给未声明的属性赋值会记一条 Deprecated: Creation of dynamic property App\Order\Order::$couponCode is deprecated,不再默认创建。要么在类里声明 public ?string $couponCode = null;,要么给这个类加 #[AllowDynamicProperties];后者只是把问题推迟,建议只留给第三方老库。
  • ${} 插值:报错文本是 Deprecated: Using ${var} in strings is deprecated, use {$var} instead,模板文件里最常见,改成 "{$var}" 即可,行为不变。
  • 比较规则:PHP 8 起 0 == "abc" 的结果从 true 变成 false,数字和非数字字符串比较不再先转成数字。以前靠这个宽松比较放行的判断会突然拦住人,必须改成显式判断。
  • 稳定排序:PHP 8.0 起 sort、usort 都是稳定排序,值相等的元素保持原顺序。以前「相等时顺序随机」的分页、排行榜,现在顺序固定了,看起来更对,但如果有代码依赖旧的乱序结果做分页游标,翻页会重复或漏项。
  • TypeError 变多:内置函数对参数类型更严格,strlen(null) 会报 Deprecated: strlen(): Passing null to parameter #1 ($string) of type string is deprecated,开了严格类型后用户函数传错类型直接抛 TypeError。
var_dump(0 == "abc");   // PHP 7: true,PHP 8: false
var_dump("1" == "01");  // true
var_dump(100 == "1e2"); // true

还有一处是彻底移除,不只是废弃:each() 在 8.0 被删掉,老循环里写 while (list($k, $v) = each($items)) 的,升级后会直接 PHP Fatal error: Uncaught Error: Call to undefined function each(),必须改成 foreach。这类改动没有兼容写法,只能逐个替换。

类型声明与 strict_types

现代 PHP 的第一个特征是把类型写清楚。参数、返回值、属性都能声明,支持可空类型和联合类型:

<?php
declare(strict_types=1);

function totalCents(array $items, ?int $couponCents = null): int
{
    $sum = 0;
    foreach ($items as $item) {
        $sum += $item['priceCents'] * $item['qty'];
    }
    return max(0, $sum - ($couponCents ?? 0));
}

function findOrder(int|string $id): ?array
{
    return null; // 示例,真实实现用 PDO
}

?int 表示可以是整数或 null,int|string 是联合类型。返回 ?array 明确告诉调用方「可能没有结果」,比返回 false 或空数组更清楚。

declare(strict_types=1) 要写在每个文件第一行。它只影响这个文件里发起的调用,别的文件没写就仍然会做类型转换,所以要么全项目统一开,要么就别指望它。升级老项目时可以先在新文件里开,旧文件逐步补。

返回值类型里有两个容易混的:void 和 never。void 表示函数没有返回值,但会正常结束,函数体里不能写 return $x;,只能写空的 return; 或者什么都不写。never 是 8.1 加的,表示函数永远不返回:要么抛异常,要么 exit/die。它最大的用处是让静态分析知道「这一行之后的代码走不到」,比如一个永远抛异常的校验函数,写在 if 里之后,后面的代码就不用再判断类型。标错了会很难查:一个实际会返回的函数标成 never,静态检查会以为后面不可达,把真正的逻辑当成死代码。

构造器提升与 readonly

PHP 8.0 的构造器提升把属性声明和赋值合并,PHP 8.1 的 readonly 让属性只能在构造时赋值,PHP 8.2 的 readonly class 可以把整个类设为只读:

<?php
declare(strict_types=1);

final readonly class Money
{
    public function __construct(
        public int $cents,
        public string $currency = 'CNY',
    ) {}

    public function add(self $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new InvalidArgumentException('币种不一致');
        }
        return new self($this->cents + $other->cents, $this->currency);
    }
}

$total = (new Money(19900))->add(new Money(3000));
echo $total->cents; // 22900

readonly class 是 PHP 8.2 的写法,8.1 只能逐个属性加 readonly。这类值对象适合只读:一旦创建就不能改,修改时返回新对象,避免了「某处偷偷改了价格」的问题。

注意 readonly 的边界:它不允许属性重新赋值,但属性是数组时,往数组里加元素也算修改;属性是对象时,对象内部状态仍可变。真正的不可变需要里面的值也不可变。

match 与空安全运算符

match 在流程控制那篇讲过,这里补两个现代写法。第一,它可以直接返回值,适合把一串条件收成规则表:

<?php
$label = match (true) {
    $amountCents >= 100000 => '大额',
    $amountCents >= 30000  => '中额',
    default                => '小额',
};

第二,match 用严格比较,不会出现 switch 那种 '0' 串到别的分支的情况。没写 default 又没匹配到,会抛 UnhandledMatchError,这是一件好事:错误尽早暴露。

空安全运算符写成 ?->,用法是这样的:

<?php
$city = $order->user?->address?->city ?? '未填写';

它只在对象为 null 时短路,数组键不存在还是要用 ??。两者经常一起用:对象链用 ?->,最后兜底用 ??。

枚举、箭头函数与第一类可调用

枚举把状态、类型这类有限集合变成类型,配合 match 可以强制覆盖所有分支:

<?php
enum Channel: string
{
    case Web = 'web';
    case App = 'app';
    case MiniProgram = 'mini';

    public function label(): string
    {
        return match ($this) {
            self::Web => '网页',
            self::App => '应用',
            self::MiniProgram => '小程序',
        };
    }
}

枚举和数据库之间还有一个实际坑:从数据库读出来的是字符串,直接写 Channel::from($row['channel']),遇到历史脏数据(空字符串、大小写不一致、旧渠道名)会抛 ValueError: "xxx" is not a valid backing value for enum App\Order\Channel,整个列表接口 500。要么在写入前做约束,要么在读取时用 Channel::tryFrom() 并给一个兜底值,别让一条脏数据带走整页。

箭头函数 fn ($x) => ... 适合短回调,自动捕获外层变量;超过一个表达式就写成普通闭包。PHP 8.1 的「第一类可调用语法」可以直接把函数变成闭包:

<?php
$lengths = array_map(strlen(...), ['a', 'bb', 'ccc']);
// [1, 2, 3]

它比写字符串 'strlen' 更安全:静态分析能识别,重构改名不会漏。

8.1 还有一个看起来很碎但用得很勤的 array_is_list()。它判断一个数组的键是不是从 0 开始、连续递增。这个判断听起来没意义,实际卡住过很多人:json_encode() 输出对象还是数组,取决于键是不是连续的整数;一个本该是列表的数组被 array_filter 或 unset 删掉中间几项后,键就断了,编码结果会变成 {"1":2,"2":3} 而不是 [2,3],前端拿到的类型跟着变。以前要自己写循环判断,现在一行 array_is_list($rows) 就能先确认,不是列表就先 array_values() 再输出。

PHP 8.1 到 8.3 还值得知道什么

  • 8.1:枚举、readonly 属性、交集类型、never 返回类型、array_is_list()、用 new 初始化默认参数。
  • 8.2:readonly 类、独立类型 true/false/null、动态属性废弃、${} 插值废弃。
  • 8.3:json_validate() 只校验不解析、类常量可以声明类型、#[Override] 标注「我确实覆盖了父类方法」、Randomizer 增加几个方法。

其中两个对老项目最直接:动态属性废弃会让大量「随手给对象加字段」的代码在日志里报警;${} 插值废弃会让模板文件刷出 Deprecated。它们不会立刻 fatal,但升级到 9 之前必须清完。

json_validate() 是 8.3 新增的,作用很窄但很实用:只判断一段字符串是不是合法 JSON,不把它解析成数组或对象。旧写法是先 json_decode(),再判断 json_last_error(),几十 KB 的字符串即使格式错也要先交给解析器走一遍。要校验的是大请求体、而且校验后不一定马上用,这个差别就出来了。注意它只回答「语法对不对」,不回答「结构符不符合业务要求」,字段是否存在、类型是否正确仍然要自己查。

不确定某个函数在目标版本里是什么状态时,先查官方迁移文档,再在本机用目标版本跑一遍。php -l 只能查语法,查不出「函数被移除」,需要实际执行或者静态扫描。

场景走查:一个订单模块的升级

需求:把一个订单计算模块从 PHP 7.4 升到 8.3,行为不能变,性能不能退。这个模块的旧代码大致是这样:

<?php
// 旧代码,PHP 5 风格的典型写法
$discount = create_function('$total', 'return $total >= 20000 ? 3000 : 0;');

function calc_total($items)
{
    global $discount;
    $total = 0;
    while (list($k, $v) = each($items)) {
        $total += $v['price'] * $v['qty'];
    }
    return $total - $discount($total);
}

第一步只做「能跑」:each() 换成 foreach,create_function() 换成箭头函数,global 改成参数传入。此时行为完全不变,测试通过。

<?php
declare(strict_types=1);

$discount = fn (int $total): int => $total >= 20000 ? 3000 : 0;

function calcTotal(array $items, callable $discount): int
{
    $total = 0;
    foreach ($items as $item) {
        $total += $item['priceCents'] * $item['qty'];
    }
    return $total - $discount($total);
}

第二步把「元」换成「分」,字段名从 price 改成 priceCents,顺手解决了浮点误差。这一步会动数据,所以要同时改数据库字段和导入逻辑,属于有风险的变更,单独发布。

第三步把数组换成值对象和枚举,价格计算变成 Money 的方法,渠道变成 Channel 枚举。这一步不改变外部行为,但让类型和单位固定下来。

第四步在测试环境开 E_ALL,把 Deprecated 全部看一遍,能改的改掉,不能改的记录下来。然后用 PHPCompatibility 扫全项目,确认没有遗漏的移除函数。

定位顺序也要固定,从便宜到贵。第一步 php -l 扫全项目,语法错会在升级当天直接 500,必须先清干净:

$ find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 -P4 php -l
No syntax errors detected in ./src/Order/OrderService.php

第二步跑测试。没有测试就至少跑关键页面的冒烟脚本,让请求真的发出去,比 php -l 能多抓一类问题。第三步看 Deprecated 日志:把 error_reporting 开到 E_ALL,跑一遍主要流程,再按出现次数排序,grep -h "Deprecated:" var/log/php*.log | sort | uniq -c | sort -rn | head -n 20,出现最多的那条就是最该先改的。第四步才上静态扫描,PHPCompatibility 按 8.3 扫一遍,把 php -l 和运行都抓不到的移除函数、废弃语法补出来。

这个顺序的道理是,前一步能排除的原因,后一步就不用再查。php -l 通过不代表能跑,能跑不代表没警告,没警告也不代表没有被移除的 API 藏在没人走的分支里,四步各管一段。

上线策略:先灰度一台机器,观察错误日志和关键接口的返回;确认无误再全量。发布脚本保留旧版本软链,出问题十分钟内切回。数据库变更单独做,别和代码发布绑在一起。

灰度最容易出的事故是「新旧混跑」。四台机器,先切一台,其余三台还是旧版本,负载均衡轮询,同一秒的不同请求会落到不同代码上。表现是只有一部分用户 500,刷新几次时好时坏,日志里同时出现两类记录:PHP Fatal error: Uncaught Error: Call to undefined function App\Support\release_note() in /var/www/releases/20261106/src/Order/Checkout.php:88,以及 Deprecated: Creation of dynamic property App\Order\Order::$couponCode is deprecated in /var/www/releases/20260901/src/Order/Order.php:31。

先别急着改代码,先确认是不是混跑。看日志里的绝对路径:两条记录分别落在 20261106 和 20260901 两个 release 目录,说明它们不是同一份代码产生的。再逐台核对 readlink -f /var/www/app,灰度机指向新目录,其余仍指旧目录,这就是标准的灰度中间态。然后查那个未定义函数在本机到底存不存在:php -r "require 'vendor/autoload.php'; var_dump(function_exists('App\\Support\\release_note'));",输出 bool(true) 说明新代码和 autoload 都没问题,是请求落到了没升级的机器;输出 bool(false) 才说明这台机器的 autoload 或 vendor 没跟上。

确认之后只有两个正确动作:要么把这一台也回滚到旧版本,要么把其余机器一次性升到新版本,不要留在中间态观察「会不会自己好」。中间态期间,任何依赖新旧代码一致性的功能都会出问题,比如新代码写入的新字段,旧代码读不出来,用户看到的是数据丢失。发布脚本里应当把「切换软链、reload、版本号校验」做成一个不可分割的步骤,四台全部通过才摘掉灰度标记。

现象、原因与第一步

现象真实原因第一步查什么
Call to undefined function each()PHP 8.0 移除了这个函数全局搜索旧函数名,按清单替换
Call to undefined function mysql_connect()mysql 扩展在 7.0 就被移除换 PDO 或 mysqli,改所有查询
日志刷 Creation of dynamic property8.2 起给未声明属性赋值会废弃警告搜赋值语句,补属性声明
模板里出现 Deprecated: ${}8.2 废弃了这种插值写法改成 "{$var}"
升级后大量 TypeError开了严格类型,旧调用传的是字符串看异常里的参数类型,在边界处显式转换
UnhandledMatchError输入值没有对应的 match 分支补分支或加 default 并记录原始值
列表顺序和以前不一样PHP 8.0 起排序变成稳定排序确认业务是否依赖旧的非稳定顺序
升级后登录校验失效旧密码哈希方式或二次转义逻辑不兼容检查 password_verify 和入库前的处理

边界与代价

不要为了用新语法而重写能跑的代码。构造器提升、match、枚举的价值在于减少错误,不在于「看起来现代」。一个已经稳定运行、没人改的模块,保持原样往往比改写成新风格更划算。

严格类型是一把双刃剑。新代码开启后,任何来自 HTTP、数据库、配置的字符串都会在边界处暴露出来,这是好事;但老代码没有类型声明,混合调用时会在意想不到的地方抛 TypeError。分文件、分模块推进,比一次性全开安全。

升级的代价不止代码。扩展要装齐(mbstring、pdo_mysql、intl 等),框架和依赖要升级,部署脚本要检查 OPcache 和 FPM,监控要能识别新错误。任何一项漏掉,都会在发布当天变成事故。

还有一个常被低估的成本:测试。老项目往往没什么自动化测试,升级前靠人点页面来验证,改动一多就点不过来。比较稳的做法是升级前先给最关键的几条路径补上「能跑起来就算过」的冒烟测试:下单金额对不对、登录能不能进、列表能不能查出来。这些测试不需要写得漂亮,只要能在一个命令里跑完、失败时能指出是哪条路径断了,就足以把升级当天的问题从「用户投诉」提前到「发布前发现」。反过来,如果没有这层兜底,就只能靠灰度 + 快速回滚,风险明显更高。

PHP 8 的性能提升主要来自 OPcache 和语言内部优化,不是 JIT。不要为了追性能数字打开 JIT 却忽略索引和进程数,收益通常不成比例。

当天能自己验证的练习

  1. 在 8.3 环境运行一段 each() 和 create_function(),确认报错信息;再改写成 foreach 和箭头函数。
  2. 给一个类加 readonly class,尝试在构造后修改属性,观察报错;再试一次「属性是数组,往里加元素」。
  3. 用 match (true) 写一个金额分档,故意漏掉一个区间,看是否抛 UnhandledMatchError。
  4. 用 ?-> 和 ?? 读取一个可能为 null 的对象链,构造几种 null 位置,确认都能兜住。
  5. 把一个老函数加上参数和返回类型,开启 strict_types,用字符串参数调用,观察 TypeError,再在调用处显式转换。

小结

三句话:升级先清移除的 API,再处理废弃警告,最后才是语法现代化;新写法里最值得用的是类型声明、构造器提升、match、枚举和空安全运算符;新语法是为了减少错误,不是为了看起来新。

到这里,PHP 这组的基础篇告一段落。从一次请求怎么变成页面,到语法、数组、对象、依赖、数据库、会话、安全、结构、部署,最后回到现代写法,这条线覆盖了一个 PHP 项目从写第一行到上线的全过程。后面还有运行时层面的内容:文件与流、网络通信、多进程与文件锁、异步,以及共享内存与缓存。接下来可以按学习路线继续,也可以直接找一个自己的小项目,把留言板从数组版一路改到有结构、有测试、能部署的版本。