前言先看一段几乎人人都写过的调用代码?php $user createUser(张三, zhangsanexample.com, true, null, 9);读这行代码的人会立刻卡住第三个参数true是开关什么第四个null又是哪个字段如果哪天只想把最后一个$level从 1 改成 9你仍然必须把前面两个其实不想动的可选参数一起写上还得准确地背出它们的默认值。参数一多调用点就变成了谜语。命名参数Named Arguments也叫命名实参就是为解决这件事而引入的语法调用时写成参数名: 值顺序不再重要中间不想传的参数可以整段跳过。需要说清楚版号这个特性确确实实由PHP 8.0引入和match表达式、构造函数属性提升constructor property promotion、?-是同一批进入 8.0 的语言特性标题里的 8.0 是准确的。本文讲三件事命名参数的语法与三条硬性规则、它和可变参数variadic及数组展开argument unpacking的配合方式以及在实际项目里怎么用它写出可读的 API。文中所有示例都能直接存成.php运行最低版本 PHP 8.0涉及 8.1 的部分会单独标注。一、语法与三条硬规则命名参数的基本形态就是在实参前加上形参名和一个冒号?php declare(strict_types1); function createUser( string $name, string $email, bool $active true, ?string $nickname null, int $level 1, ): array { return [ name $name, email $email, active $active, nickname $nickname, level $level, ]; } // 只关心 level中间三个可选参数全部跳过 var_dump(createUser(张三, zexample.com, level: 9));输出array(5) { [name] string(6) 张三 [email] string(12) zexample.com [active] bool(true) [nickname] NULL [level] int(9) }被跳过的参数走的是它们各自的默认值走默认值的表达式仍然按声明顺序求值。规则只有三条但每一条都是硬约束违反就抛Error规则一位置参数必须写在命名参数之前。一旦出现命名参数后面就不能再出现位置参数。createUser(name: 张三, zexample.com); // Error: Cannot use positional argument after named argument规则二同一个参数不能传两次。位置参数和命名参数指向同一个形参也算重复。createUser(张三, zexample.com, active: true, active: false); // Error: Named parameter $active overwrites previous argument规则三没有对应形参的命名参数会报错除非函数声明了可变参数下一节讲。createUser(张三, zexample.com, gender: male); // Error: Unknown named parameter $gender二、和可变参数、数组展开怎么配合PHP 8.0 起命名参数可以流进可变参数多余的名字会以字符串键的形式被收集到可变参数数组里。这一点非常有用因为它是把任意键值配置透传给下游的唯一入口。?php declare(strict_types1); function tag(string $first, string ...$rest): array { return [$first, $rest]; } var_dump(tag(core, version: 8.0, channel: stable));输出array(2) { [0] string(4) core [1] array(2) { [version] string(3) 8.0 [channel] string(6) stable } }注意$rest的键是字符串而不是通常的位置下标——这正是命名参数的痕迹。再看数组展开。PHP 8.1 之前展开运算符spread只接受整数键PHP 8.1 起允许字符串键的数组展开于是用数组一次性喂入命名参数成为可能?php // 需要 PHP 8.1 及以上 declare(strict_types1); $payload [email liexample.com, name 李四, level 3]; var_dump(createUser(...$payload));展开顺序同样受规则一约束createUser(李四, ...$payload)在$payload里含name时会因为重复传参而报错。三、实战一个可运行的配置构建器下面这个例子把命名参数用在真实场景里——数据库连接配置。它带校验、带默认值调用点自解释可以直接跑?php // demo.php —— 需要 PHP 8.0 及以上 declare(strict_types1); final class Dsn { public function __construct( private string $driver, private string $host, private int $port, private string $database, private string $charset utf8mb4, private array $options [], ) { if ($this-port 1 || $this-port 65535) { throw new InvalidArgumentException(端口不合法: {$this-port}); } } public function __toString(): string { return sprintf( %s:host%s;port%d;dbname%s;charset%s, $this-driver, $this-host, $this-port, $this-database, $this-charset, ); } } // 只写必填项端口用默认之外的写法显式传 $dsn new Dsn( driver: mysql, host: 127.0.0.1, port: 3306, database: app, ); echo $dsn, PHP_EOL; // 跳过 charset直接补 options $dsn2 new Dsn( driver: mysql, host: 127.0.0.1, port: 3307, database: report, options: [PDO::ATTR_TIMEOUT 3], ); echo $dsn2, PHP_EOL;对照老写法差别一眼可见场景PHP 7.4 及以前PHP 8.0 命名参数只改第 5 个可选参数必须补全前面所有参数level: 9直接跳过记忆参数顺序必须不需要调用点可读性true, null, 9全靠猜active: true, level: 9自解释内部函数调用只能按位置传名字对得上就能换序参数改名只是文档问题变成对调用方的破坏性变更四、它对内部函数意味着什么命名参数同样适用于内部函数例如str_contains(haystack: $s, needle: x)是合法的。这也是 PHP 8.0 在升级文档里批量重命名内部函数参数名的原因——名字从此对外可见必须保持一致的命名风格。相应地内部函数的参数名改动在语义上属于破坏性变更官方对此比较克制但把命名参数用在与版本强相关的扩展函数上时仍要多留一分心。?php // 需要 PHP 8.0 及以上 declare(strict_types1); $sql SELECT * FROM users WHERE name LIKE ?; // 名字对得上顺序随便换 var_dump(str_contains(haystack: $sql, needle: WHERE)); // bool(true) // 数组式调用call_user_func_array在 PHP 8.0 起也会把字符串键当参数名 $args [name 王五, email wangexample.com]; var_dump(call_user_func_array(createUser, $args)[name]);常见坑点❌ 把位置参数写在命名参数后面例如f(name: a, b)✅ 位置参数一律前置f(b, name: a)否则直接Error: Cannot use positional argument after named argument❌ 在一次调用里对同一个形参既给位置值又给命名值甚至给两次命名值✅ 一个形参只写一次位置参数与命名参数会撞车报Named parameter $x overwrites previous argument❌ 给没有声明该形参、也没有可变参数的函数传命名参数指望它被顺便带上✅ 想接收任意命名参数函数签名里必须写...$rest否则报Unknown named parameter❌ 用命名参数调用第三方库后对方把形参改了个名就以为不影响自己✅ 重命名形参对外部调用方是破坏性变更对跨版本升级不友好的代码公共 API 上慎重使用❌ 在 PHP 8.0 里用[email ...]这样带字符串键的数组去展开传参✅ 字符串键展开是PHP 8.1才支持的8.0 上会报Cannot unpack array with string keys❌ 以为可变参数收集到的命名参数下标还是0,1,2✅ 被命名参数填充的项在可变参数数组里是字符串键foreach时不要假设array_values的语义❌ 依赖可选参数的默认值表达式被跳过了就不会执行✅ 传了后面的命名参数时前面跳过的参数依然会按声明顺序用默认值补齐默认值里有副作用比如调用函数时要注意❌ 把构造器属性提升的形参名当成纯内部命名随意改动✅ 提升后的形参名同时是属性名既是命名参数契约又是对外接口改名前先搜调用点总结维度说明引入版本PHP 8.0语法func(param: value)比较/匹配语义按形参名绑定与值类型无关位置参数位置要求必须在所有命名参数之前重复传参报Error同一形参只能出现一次未知名字有可变参数则收集为字符串键否则报Error数组展开配合字符串键展开需 PHP 8.1 及以上主要收益跳过可选参数、调用点自解释、参数顺序解耦命名参数最大的价值不是省几个字符而是把参数顺序从调用契约里拿掉让调用点自己说明自己。代价是把形参名变成了公开 API 的一部分——所以在自己项目的公共方法上放心用在需要长期兼容多版本的地方则要把它当成一次契约承诺来对待。
前言先看一段几乎人人都写过的调用代码?php $user createUser(张三, zhangsanexample.com, true, null, 9);读这行代码的人会立刻卡住第三个参数true是开关什么第四个null又是哪个字段如果哪天只想把最后一个$level从 1 改成 9你仍然必须把前面两个其实不想动的可选参数一起写上还得准确地背出它们的默认值。参数一多调用点就变成了谜语。命名参数Named Arguments也叫命名实参就是为解决这件事而引入的语法调用时写成参数名: 值顺序不再重要中间不想传的参数可以整段跳过。需要说清楚版号这个特性确确实实由PHP 8.0引入和match表达式、构造函数属性提升constructor property promotion、?-是同一批进入 8.0 的语言特性标题里的 8.0 是准确的。本文讲三件事命名参数的语法与三条硬性规则、它和可变参数variadic及数组展开argument unpacking的配合方式以及在实际项目里怎么用它写出可读的 API。文中所有示例都能直接存成.php运行最低版本 PHP 8.0涉及 8.1 的部分会单独标注。一、语法与三条硬规则命名参数的基本形态就是在实参前加上形参名和一个冒号?php declare(strict_types1); function createUser( string $name, string $email, bool $active true, ?string $nickname null, int $level 1, ): array { return [ name $name, email $email, active $active, nickname $nickname, level $level, ]; } // 只关心 level中间三个可选参数全部跳过 var_dump(createUser(张三, zexample.com, level: 9));输出array(5) { [name] string(6) 张三 [email] string(12) zexample.com [active] bool(true) [nickname] NULL [level] int(9) }被跳过的参数走的是它们各自的默认值走默认值的表达式仍然按声明顺序求值。规则只有三条但每一条都是硬约束违反就抛Error规则一位置参数必须写在命名参数之前。一旦出现命名参数后面就不能再出现位置参数。createUser(name: 张三, zexample.com); // Error: Cannot use positional argument after named argument规则二同一个参数不能传两次。位置参数和命名参数指向同一个形参也算重复。createUser(张三, zexample.com, active: true, active: false); // Error: Named parameter $active overwrites previous argument规则三没有对应形参的命名参数会报错除非函数声明了可变参数下一节讲。createUser(张三, zexample.com, gender: male); // Error: Unknown named parameter $gender二、和可变参数、数组展开怎么配合PHP 8.0 起命名参数可以流进可变参数多余的名字会以字符串键的形式被收集到可变参数数组里。这一点非常有用因为它是把任意键值配置透传给下游的唯一入口。?php declare(strict_types1); function tag(string $first, string ...$rest): array { return [$first, $rest]; } var_dump(tag(core, version: 8.0, channel: stable));输出array(2) { [0] string(4) core [1] array(2) { [version] string(3) 8.0 [channel] string(6) stable } }注意$rest的键是字符串而不是通常的位置下标——这正是命名参数的痕迹。再看数组展开。PHP 8.1 之前展开运算符spread只接受整数键PHP 8.1 起允许字符串键的数组展开于是用数组一次性喂入命名参数成为可能?php // 需要 PHP 8.1 及以上 declare(strict_types1); $payload [email liexample.com, name 李四, level 3]; var_dump(createUser(...$payload));展开顺序同样受规则一约束createUser(李四, ...$payload)在$payload里含name时会因为重复传参而报错。三、实战一个可运行的配置构建器下面这个例子把命名参数用在真实场景里——数据库连接配置。它带校验、带默认值调用点自解释可以直接跑?php // demo.php —— 需要 PHP 8.0 及以上 declare(strict_types1); final class Dsn { public function __construct( private string $driver, private string $host, private int $port, private string $database, private string $charset utf8mb4, private array $options [], ) { if ($this-port 1 || $this-port 65535) { throw new InvalidArgumentException(端口不合法: {$this-port}); } } public function __toString(): string { return sprintf( %s:host%s;port%d;dbname%s;charset%s, $this-driver, $this-host, $this-port, $this-database, $this-charset, ); } } // 只写必填项端口用默认之外的写法显式传 $dsn new Dsn( driver: mysql, host: 127.0.0.1, port: 3306, database: app, ); echo $dsn, PHP_EOL; // 跳过 charset直接补 options $dsn2 new Dsn( driver: mysql, host: 127.0.0.1, port: 3307, database: report, options: [PDO::ATTR_TIMEOUT 3], ); echo $dsn2, PHP_EOL;对照老写法差别一眼可见场景PHP 7.4 及以前PHP 8.0 命名参数只改第 5 个可选参数必须补全前面所有参数level: 9直接跳过记忆参数顺序必须不需要调用点可读性true, null, 9全靠猜active: true, level: 9自解释内部函数调用只能按位置传名字对得上就能换序参数改名只是文档问题变成对调用方的破坏性变更四、它对内部函数意味着什么命名参数同样适用于内部函数例如str_contains(haystack: $s, needle: x)是合法的。这也是 PHP 8.0 在升级文档里批量重命名内部函数参数名的原因——名字从此对外可见必须保持一致的命名风格。相应地内部函数的参数名改动在语义上属于破坏性变更官方对此比较克制但把命名参数用在与版本强相关的扩展函数上时仍要多留一分心。?php // 需要 PHP 8.0 及以上 declare(strict_types1); $sql SELECT * FROM users WHERE name LIKE ?; // 名字对得上顺序随便换 var_dump(str_contains(haystack: $sql, needle: WHERE)); // bool(true) // 数组式调用call_user_func_array在 PHP 8.0 起也会把字符串键当参数名 $args [name 王五, email wangexample.com]; var_dump(call_user_func_array(createUser, $args)[name]);常见坑点❌ 把位置参数写在命名参数后面例如f(name: a, b)✅ 位置参数一律前置f(b, name: a)否则直接Error: Cannot use positional argument after named argument❌ 在一次调用里对同一个形参既给位置值又给命名值甚至给两次命名值✅ 一个形参只写一次位置参数与命名参数会撞车报Named parameter $x overwrites previous argument❌ 给没有声明该形参、也没有可变参数的函数传命名参数指望它被顺便带上✅ 想接收任意命名参数函数签名里必须写...$rest否则报Unknown named parameter❌ 用命名参数调用第三方库后对方把形参改了个名就以为不影响自己✅ 重命名形参对外部调用方是破坏性变更对跨版本升级不友好的代码公共 API 上慎重使用❌ 在 PHP 8.0 里用[email ...]这样带字符串键的数组去展开传参✅ 字符串键展开是PHP 8.1才支持的8.0 上会报Cannot unpack array with string keys❌ 以为可变参数收集到的命名参数下标还是0,1,2✅ 被命名参数填充的项在可变参数数组里是字符串键foreach时不要假设array_values的语义❌ 依赖可选参数的默认值表达式被跳过了就不会执行✅ 传了后面的命名参数时前面跳过的参数依然会按声明顺序用默认值补齐默认值里有副作用比如调用函数时要注意❌ 把构造器属性提升的形参名当成纯内部命名随意改动✅ 提升后的形参名同时是属性名既是命名参数契约又是对外接口改名前先搜调用点总结维度说明引入版本PHP 8.0语法func(param: value)比较/匹配语义按形参名绑定与值类型无关位置参数位置要求必须在所有命名参数之前重复传参报Error同一形参只能出现一次未知名字有可变参数则收集为字符串键否则报Error数组展开配合字符串键展开需 PHP 8.1 及以上主要收益跳过可选参数、调用点自解释、参数顺序解耦命名参数最大的价值不是省几个字符而是把参数顺序从调用契约里拿掉让调用点自己说明自己。代价是把形参名变成了公开 API 的一部分——所以在自己项目的公共方法上放心用在需要长期兼容多版本的地方则要把它当成一次契约承诺来对待。
