PHP：@template注解与@throws标签结合使用的问题咨询

核心误解：@template 并非用于传递异常类型 #

你错误地将@template注解用于传递异常类型，但@template的设计目的是泛型类型约束（比如定义集合类的元素类型、通用容器的类型参数），它和@throws没有直接关联，PhpStorm也不会通过泛型参数自动推导方法的抛出异常类型。

具体错误与修正步骤 #

1. 移除异常类型的@template声明
   如果你之前用@template传递异常类型（类似下面的错误写法）：

   /**
    * @template TException of \Throwable
    * @param mixed $value
    * @return int
    * @throws TException
    */
   function valueIsIntOrThrow($value) {
       if (!is_int($value)) {
           throw new TException("Not an int"); // 泛型参数不能直接实例化，属于语法错误
       }
       return $value;
   }
   

   这种写法不符合PHPDoc规范，PhpStorm会报错且无法识别异常类型。必须移除异常相关的@template参数，改为直接指定具体异常类型：

   /**
    * @param mixed $value
    * @return int
    * @throws \ErrorException
    */
   function valueIsIntOrErrorException($value) {
       if (!is_int($value)) {
           throw new \ErrorException("Not an int");
       }
       return $value;
   }
   
   /**
    * @param mixed $value
    * @return int
    * @throws \CustomErrorException
    */
   function valueIsIntOrCustomErrorException($value) {
       if (!is_int($value)) {
           throw new \CustomErrorException("Not an int");
       }
       return $value;
   }
   

2. 让PhpStorm自动生成@throws的正确方式
   PhpStorm只会在方法内部直接抛出具体异常类实例时，才会提示生成@throws注释：

   • 在写完throw new XXXException()后，将光标移到方法上方的PHPDoc区域，按Alt+Enter（Windows/Linux）或Option+Enter（Mac），选择"Add @throws tag"
   • 开启IDE检查：进入Settings > Editor > Inspections > PHP > PHPDoc > Missing @throws tag，勾选后IDE会自动检测未声明的抛出异常并提示添加。

3. 调用带@throws方法的处理
   对于调用其他带@throws方法的函数（比如你的test3和valueIsIntOrCustomErrorException），PhpStorm默认不会自动继承异常注释，需按以下规则处理：

   • 如果当前方法未捕获被调用方法的异常，手动添加对应的@throws注释
   • 如果捕获了异常，无需添加对应@throws（除非捕获后重新抛出了其他异常）

关键注意事项 #

• @template仅用于类型参数（比如@template T of \Model表示集合元素类型为T），不能用于异常类型传递
• PhpStorm解析@throws依赖具体的异常类实例，必须在代码中明确抛出具体异常类，IDE才能识别并生成注释
• 手动添加@throws时要确保异常类已存在（无拼写错误、已引入命名空间），否则IDE会报错

内容的提问来源于stack exchange，提问作者Mirko Pagliai