PHPStan中构造函数属性提升(Promoted Properties)的文档注释规范

问题背景

在PHP 8.0中引入的构造函数属性提升(Promoted Properties)功能允许开发者直接在构造函数参数中声明类属性，这一语法糖简化了代码编写。然而，在使用PHPStan进行静态分析时，开发者可能会遇到关于类型提示文档注释的困惑。

文档注释的正确使用方式

对于构造函数属性提升，PHPStan支持两种标准的文档注释方式：

1. 构造函数参数文档(@param)

/**
 * @param array<int, string> $param
 */
public function __construct(
    public array $param
) {}

这种方式与普通函数参数的文档注释方式一致，将类型提示写在构造函数上方的文档块中，使用@param标签。

2. 属性文档(@var)

public function __construct(
    /** @var array<int, string> */
    public array $param
) {}

这种方式直接在提升属性前使用@var注释，与常规类属性的文档注释方式相同。

常见误区

开发者容易犯的错误包括：

1. 试图在提升属性参数上使用@param注释
2. 在错误的层级放置文档注释
3. 混淆参数文档和属性文档的使用场景

最佳实践建议

1. 对于主要作为参数使用的提升属性，推荐使用构造函数@param文档
2. 对于主要作为类属性使用的提升属性，推荐使用@var文档
3. 保持团队内部风格一致，避免混用两种方式
4. 复杂的类型提示(如泛型)应确保文档注释的准确性

通过遵循这些规范，可以确保PHPStan能够正确识别类型信息，同时保持代码的可读性和可维护性。