PHP 8.0+ 中用 mixed 或 array 注释可变参数最稳妥，因 PHP 原生不支持 …$args 类型化注释，需依赖 PHPDoc；@param array $parts 正确，@param string …$parts 非法。
PHP 8.0+ 中用 mixed 或 array 注释可变参数最稳妥
PHP 原生不支持对 ...（splat operator）展开的可变参数做类型化注释，IDE 和静态分析工具（如 PHPStan、Psalm）依赖 PHPDoc 来推断类型。直接写 mixed 虽然安全，但丢失语义；若实际只接受数组元素，应优先用 array 或更具体的 array。
-
@param mixed ...$args：通用写法，适用于参数类型完全不确定的场景（如日志函数log(string $level, ...$args)） -
@param string ...$parts：错误写法 —— PHPDoc 不识别这种语法，会被忽略，IDE 无法提示类型 -
@param array ...$items：同样无效，...作用于变量，不是类型；正确做法是注释接收方参数为array，并在文档中说明“传入多个值将被收集为数组”
PHP 7.4–8.0 用 @param array $args + 文字说明代替可变参数注释
低版本 PHP 不支持 mixed，且 ...$args 在函数签名中是语法糖，实际形参仍是单个数组变量。此时 PHPDoc 应注释这个“接收容器”，而非幻想中的“多个参数”。
/**
* 拼接路径片段，支持任意数量参数
* @param string $base 起始路径
* @param array $parts 实际传入的所有额外路径段（由 ...$parts 自动收集）
* @return string
*/
function joinPath(string $base, ...$parts): string {
return implode(DIRECTORY_SEPARATOR, array_merge([$base], $parts));
}
- 不要写
@param string ...$parts—— 这不是合法 PHPDoc，解析器会跳过 - 把
...$parts当作一个隐式array参数来注释，配合文字说明其来源 - 如果函数内部明确要求每个
$parts元素是string，可写@param array（PHPStan 支持）$parts
IDE 提示不准？检查是否启用了 PHP 8+ 语言模式和 PHPStan 配置
PhpStorm 对 mixed 和 ...$args 的感知依赖项目 PHP 版本设置和插件配置。即使写了正确的 PHPDoc，若语言级别设为 PHP 7.2，mixed 会被标黄或忽略。
- PhpStorm：File → Settings → Languages & Frameworks → PHP → Language level → 设为
8.0或更高 - PHPStan：确保
phpstan.neon中未禁用mixed类型检查（默认开启） - VS Code + intelephense：确认
"intelephense.environment.phpVersion"设置为"8.0"或以上
别用 @param callable ...$callbacks 这种写法
这是常见误解 —— 以为能给“每个可变参数”单独加类型。实际上，... 是运行时行为，PHPDoc 只能描述函数声明中出现的变量名及其整体类型。所谓“多个 callable”，本质仍是“一个数组，里面全是 callable”。
立即学习“PHP免费学习笔记（深入）”；
/**
* 批量注册回调，支持传入任意数量
* @param callable[] $callbacks 所有传入的回调函数（自动收集为数组）
*/
function on(string $event, ...$callbacks): void {
foreach ($callbacks as $cb) {
if (!is_callable($cb)) {
throw new InvalidArgumentException('Expected callable');
}
// ...
}
}
真正容易被忽略的是：PHPDoc 里的类型必须与运行时结构一致。你写 callable[]，就得保证 $callbacks 确实是数组；如果函数里还允许传单个 callable（非数组），那就得用 callable|array，并手动处理兼容逻辑。