如何记录期望常量的参数

Question

什么是记录其值预期为预定义常量的函数或方法参数的推荐方法？到目前为止,我使用常量的数据类型,稍后我会添加一些解释.

例如:

<?php

class Foo{
    const METHOD_GET = 'get';
    const METHOD_POST = 'post';

    /**
     * Load a new foo
     *
     * @param string $method HTTP method to use (either Foo::METHOD_GET or Foo::METHOD_POST)
     */
    public function load($method=Foo::METHOD_POST){
        // ...
    }

    /**
     * Sort current foo
     *
     * @param int $sort_order Sort order (either SORT_ASC or SORT_DESC)
     */
    public function sort($sort_order=SORT_ASC){
        // ...
    }
}

Answer 1

#1：仅限 PHPStorm 选项，适用于所有 PHP 版本

虽然不规范，但目前可以通过 PHPStorm 内参数的选项列表来实现自动完成，以防它在您的团队中很常见。它使用新的 PHP8 注释，但不需要 PHP8 - 因为目标只是解析源代码并获得自动完成。

由于它（不幸的是）不是官方 PHPDoc 标准的一部分，因此对于简单方法来说它有点难看，因为您需要完整的（可能很长）额外的行来正确记录选项，但它仍然比没有文档好。

请参阅他们关于该主题的官方帖子，但以下是同一篇帖子中的示例：

#2：PHP 范围内的选项，但仅从 8.1 开始

PHP 8.1 将采用枚举，这是值列表的“官方”版本。枚举可以用作参数的类型，这将以官方方式解决我们遇到的相同问题，并且 PHPDoc 可以支持而不包含新语法 - 并且实际上在运行时强制执行参数检查！您可以在另一篇 PHPStorm 帖子中了解更多信息（完全没有隶属关系，我只是碰巧通过他们发现了该功能，所以我尊重来源）。

Answer 2

鉴于您可以使用已知类作为param和return标记中的dataype,我还希望您可以使用已知常量.如果要指定多个类型选项,只需使用管道分隔列表.修改你的例子:

/**
 * Load a new foo
 *
 * @param Foo::METHOD_GET|Foo::METHOD_POST $method HTTP method to use
 */
public function load($method=Foo::METHOD_POST){
    // ...
}

由于这种情况下的数据类型是已知的内部到类值,因此它甚至可以在没有类名前缀的情况下工作:

* @param METHOD_GET|METHOD_POST $method HTTP method to use