PHP docblock 注释中如何正确标注 timestamp 时间戳类型

合法的PHPDoc时间戳类型标注方式 #

Unix时间戳本质是正整型，PHPDoc官方规范没有内置timestamp原生类型，你原来的写法属于未声明的自定义类型，确实不符合通用规范，常用的合法标注有以下几种：

• 通用兼容写法（适配所有IDE/静态分析工具）
  直接声明整型，搭配注释说明时间戳的精度即可，这是兼容性最好的写法，不会出现未知类型警告：

  /**
   * @return array<int, int> 数组值为秒级Unix时间戳
   */
  

• 静态分析工具强化写法（适配PHPStan/Psalm）
  如果你用了PHPStan或Psalm这类静态分析工具，可以先声明类型别名，再用自定义的时间戳类型标注，还可以额外限制数值范围：

  /**
   * @phpstan-type UnixTimestamp int<0, max> 秒级Unix时间戳
   */
  class MyAwesomeService {
      /**
       * @return array<int, UnixTimestamp>
       */
      public function myAwesomeMethod(): array
      {
          return [
              1636380000,    
              1636385555,
              1636386666,
          ];
      }
  }
  

  这种写法的好处是静态分析工具会自动校验返回的数值是否符合时间戳的范围要求，也能让代码的类型语义更清晰。
• IDE友好写法
  如果你只需要IDE识别、不需要强校验，也可以用int<timestamp>的格式，部分主流IDE（比如PhpStorm）原生支持这种写法，会自动识别为时间戳类型，甚至能帮你自动转换为可读日期预览。

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