php抽象类必须用@abstract标签标识，配合@method显式声明抽象方法、@template泛型、@throws异常及@param构造参数，禁用@inheritdoc和@var（非常量属性），否则导致ide类型推导失败。
PHP 中抽象类的注释没有特殊语法，但必须用 PHPDoc 标准写清楚 abstract 属性、继承约束和子类需实现的方法，否则 IDE 无法正确推导类型、静态分析会失效。
抽象类声明前必须加 @abstract 标签
仅靠 abstract class 关键字不足以让 PHPStan、Psalm 或 PhpStorm 明确识别其抽象语义；缺少 @abstract 会导致子类 implements 或 extends 时类型提示丢失。
-
@abstract是必需的，不能省略（哪怕类名含Abstract） - 不要写
@todo或@note替代，它们不被解析为抽象标识 - 如果类同时是泛型，
@template要放在@abstract后面
/**
* @abstract
* @template T of string
*/
abstract class AbstractUserRepository
{
// ...
}
@method 和 @see 要显式标注强制实现的方法
抽象方法本身有 abstract 修饰，但 IDE 不会自动把它们“暴露”给父类引用点；外部代码调用 $repo->find() 时，若没在抽象类 PHPDoc 中声明 @method，就会报“Method not found”。
- 每个
abstract public function都应在类级 PHPDoc 中补@method - 返回类型必须与实际声明一致，包括 nullable（
?string）、联合类型（string|int） - 可用
@see指向具体子类实现，方便跳转，但不能替代@method
/**
* @abstract
* @method User|null find(int $id)
* @method void save(User $user)
* @see MySqlUserRepository::find()
*/
abstract class AbstractUserRepository
{
abstract public function find(int $id): ?User;
abstract public function save(User $user): void;
}别在抽象类里写 @inheritdoc 注释
@inheritdoc 是给具体实现类继承父类文档用的，抽象类本身没有可继承的实现逻辑；强行加它会让 PHPStan 报 InvalidTag，且 PhpStorm 会误判为“该方法已有文档”，导致子类补文档时提示冲突。
立即学习“PHP免费学习笔记（深入）”；
- 抽象方法的文档必须写在抽象类自身 PHPDoc 中，不能依赖子类补充
- 如果多个抽象方法行为相似（如都抛
UserNotFoundException），统一在类级 PHPDoc 用@throws声明 - 避免在抽象类中使用
@var注释属性——除非是protected const，否则子类可能重定义类型
最容易被忽略的是：抽象类的构造函数如果有参数，必须在 PHPDoc 中用 @param 明确标注，哪怕它是 protected —— 因为子类 parent::__construct() 调用时，IDE 需要据此推导实参类型。
