PHP函数默认参数的注释应通过PHPDoc统一管理，@param标签不得写默认值，仅描述类型和含义；默认值语义应在自然语言说明中体现，且必须与函数签名的类型声明严格一致。
PHP函数默认参数的注释写法要匹配实际签名
PHP本身不支持在函数定义里直接为默认参数加类型或说明性注释（比如string $name = "guest" // 用户名默认值这种写法是语法错误），所有文档化信息必须通过 PHPDoc 块统一管理。关键在于：注释里的@param必须和实际参数声明完全一致，包括默认值是否出现、类型是否可为空。
PHPDoc中@param要不要写默认值
标准 PHPDoc 规范（PSR-5）不要求、也不允许在@param标签里写默认值。写进去不仅无效，还会误导静态分析工具（如 PHPStan、Psalm）或 IDE 的类型推断。
- ✅ 正确：只描述类型和含义，不提默认值
- ❌ 错误：
@param string $role 默认为 "user"或@param string $role = "user" - IDE（如 PhpStorm）会从函数签名自动提取默认值并显示在提示中，无需重复
- 如果默认值是
null且参数声明为可空（?string $role = null），则@param必须写成@param ?string $role
带默认参数的函数 PHPDoc 完整示例
/**
* 创建用户记录
* @param string $name 用户真实姓名，不能为空
* @param ?string $email 邮箱地址，可选；若提供需符合格式
* @param string $role 用户角色，默认为 "user"
* @return array 新建用户的完整数据
*/
function createUser(string $name, ?string $email = null, string $role = 'user'): array
{
return [
'name' => $name,
'email' => $email,
'role' => $role,
];
}注意三点：
-
@param ?string $email中的?表示可为空，对应?string $email = null的声明 -
@param string $role没加?，因为$role = 'user'是非空默认值，类型仍是string - 第三行注释
用户角色，默认为 "user"是自然语言说明，不是类型标注——这是唯一可写默认值的地方
常见坑：类型声明与默认值不一致导致注释失效
当默认值和类型声明冲突时，PHPDoc 注释再准确也没用，运行时或分析工具会直接报错。
立即学习“PHP免费学习笔记（深入）”；
- 错误示例：
string $id = null——null不是string，PHP 会报TypeError - 正确写法应为：
?string $id = null，对应@param ?string $id - 另一个陷阱：
array $items = []是合法的，但若写成@param array $items，PHPStan 可能无法识别空数组也是有效输入；更严谨可写@param array|list $items - 使用
declare(strict_types=1)时，这类不一致会立刻暴露，别依赖注释“掩盖”类型问题
默认参数的语义和类型必须从函数签名本身可推导，PHPDoc只是辅助说明。很多人花时间琢磨怎么在@param里塞默认值，其实该盯的是$role = 'user'这一行有没有写对类型和等号右边的值。
