PHP构造方法的PHPDoc注释必须写在__construct()上方，严格使用@param逐个标注参数类型与说明，属性提升和继承时均不可省略或简写，且须显式声明@return void。
PHP构造方法怎么写PHPDoc注释
PHP构造方法 __construct() 的注释必须放在方法声明上方，用标准PHPDoc格式，否则IDE无法识别参数类型、无法补全、生成文档也会丢失关键信息。
常见错误是只写普通注释 // 或漏掉 @param，导致类型推导失败。尤其在 Laravel、Symfony 等框架中，依赖注入参数若无明确注释，静态分析工具（如 PHPStan、Psalm）会报 Parameter $xxx of method __construct() has no type specified。
-
@param必须逐个对应构造函数实际参数，顺序、数量、名称严格一致 - 如果参数有默认值（如
= null），需在注释中标明mixed|null或具体联合类型 - 推荐使用 PHP 8+ 的原生类型声明 + PHPDoc 补充语义（例如
array这类泛型结构只能靠 PHPDoc）
/**
* 用户服务管理器
*
* @param UserRepository $userRepository 数据访问层实例
* @param LoggerInterface $logger 日志记录器，可选
* @param array{level: string, timeout: int} $options 配置选项，键名固定
*/
public function __construct(
private UserRepository $userRepository,
private ?LoggerInterface $logger = null,
private array $options = ['level' => 'info', 'timeout' => 30]
) {
}
为什么不能省略 @param 即使用了属性提升
PHP 8.0+ 支持属性提升（property promotion），看起来参数“消失”了，但 PHPDoc 注释仍需完整声明 —— 因为 IDE 和静态分析工具不从语法树反推类型，而是直接解析 PHPDoc。
例如下面这段代码，$cache 在构造函数签名里不可见，但没写 @param 就等于没告诉工具“这个类依赖 CacheInterface”：
立即学习“PHP免费学习笔记（深入）”；
- PHPStorm 不会提示该类需要传入什么参数来 new 实例
- PHPStan 默认级别就会警告 “Missing parameter type”
- 生成的 API 文档（如 with phpDocumentor）将缺失依赖说明
/**
* @param CacheInterface $cache 缓存驱动，用于加速查询
*/
public function __construct(
private CacheInterface $cache,
private string $prefix = 'user_'
) {
}
@return void 要不要写
要写，而且必须显式写 @return void。虽然构造方法隐式返回 void，但省略会导致部分工具误判（尤其是早期版本的 Psalm，默认认为无 @return 的方法可能返回 mixed）。
更关键的是：当构造方法抛出异常时，@throws 和 @return 共存是合法且推荐的。不写 @return void，@throws 可能被忽略或解析异常。
- 所有现代 PHPDoc 解析器（phpDocumentor 3、PHPStan、LSP 插件）都要求构造方法标注
@return void - 如果构造方法做了异步初始化（少见但存在），需改用
@return $this，但这是反模式，应避免
/**
* @param HttpClient $client HTTP 客户端实例
* @param string $baseUrl 接口根地址
* @return void
* @throws InvalidArgumentException 当 baseUrl 格式非法时
*/
public function __construct(HttpClient $client, string $baseUrl)
{
if (!filter_var($baseUrl, FILTER_VALIDATE_URL)) {
throw new InvalidArgumentException('Invalid base URL');
}
$this->client = $client;
$this->baseUrl = rtrim($baseUrl, '/');
}继承父类构造方法时注释怎么处理
子类重写 __construct() 时，PHPDoc 必须完整覆盖自身参数，不能用 {@inheritDoc} 简写 —— 因为父类构造方法的参数列表很可能与子类不同（常见于框架扩展、Mock 类等场景）。
即使子类只是调用 parent::__construct(...)，也必须重新写一遍全部 @param，否则 IDE 无法正确推导子类实例化所需的参数。
- 父类注释不会自动继承到子类方法上
-
{@inheritDoc}在构造方法中基本无效，PHPStan / Psalm 均不支持该标签在__construct中继承类型 - 若子类新增了参数，必须额外补充
@param；若删减了参数，必须删掉对应注释行，不能留空
/**
* 扩展版数据库连接器，支持读写分离
*
* @param string $masterDsn 主库连接串
* @param string $slaveDsn 从库连接串
* @param float $readWeight 读请求权重（0.0–1.0）
*/
public function __construct(
string $masterDsn,
string $slaveDsn,
float $readWeight = 0.7
) {
// 父类构造方法只接受单个 DSN，此处已完全重定义行为
$this->master = new PDO($masterDsn);
$this->slave = new PDO($slaveDsn);
$this->readWeight = $readWeight;
}构造方法注释不是“写完能跑就行”的环节，它直接影响类型安全、协作效率和长期可维护性。最容易被忽略的是属性提升场景下的 @param 补全，以及继承时盲目套用 {@inheritDoc}。
