如何在DocBlock中声明无限/可变参数？

Question

让我们说我有一个函数(显然是一个简单的例子):

public function dot(){
    return implode('.', func_get_args());
}

现在我知道我可以修改它

public function dot(array $items){
    return implode('.', $array);
}

但有些功能不是一种选择.那么,您如何使用docBlock记录该函数的第一个版本,以便IDE可以解释它可以接收无限制的参数？

我见过一些使用的方法:

/**
 * Joins one or more strings together with a . (dot)
 * @param string $string1
 * @param string $string2
 * @param string $_ [optional]
 * @return string
 */
public function dot($string1, $string2, $_ = null) {
    return implode('.', func_get_args());
}

在IDE中看起来像

但这对我来说就像是一个黑客攻击,有没有办法只用docBlock来做到这一点？

Answer 1

[更新2015-01-08]

在PHPDoc中执行此操作的旧方法是:

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

/**
 * @param int $param,...
 **/

但是,不再支持此功能.从PHP 5.6开始,Variadic方法参数是PHP语言的一部分,如果我没记错的话,PHPDoc已经更新以反映PHPDoc 2.4的这一点.这也是在EAP 139.659的PhpStorm IDE中(应该在8.0.2及更高版本中).不确定其他IDE的实现.

https://youtrack.jetbrains.com/issue/WI-20157

在任何情况下,适用于可变参数的DocBlocks的正确语法是:

/**
 * @param int ...$param
 **/

Answer 2

由于Variadics是在PHP 5.6中实现的,因此PHPDocumentor应支持2.4版本的以下语法.

/**
 * @param Type ...$value
 * Note: PHP 5.6+ syntax equal to func_get_args()
 */
public function abc(Type ...$value) {}

这应该是描述这种签名的正确方法.这可能会包含在PSR-5中.一旦接受,IDE应遵循以支持此"官方"建议.

然而,与此同时,一些IDE 对他们认为正确的内容有了更好的理解.在IDE供应商上努力工作以支持从5.6开始支持的官方PHP语法,或者使用同时工作的任何东西.

Answer 3

在 php 中，valist 或“可选参数”列表的概念不存在。

该$_变量将仅包含您给出的第三个字符串。允许数组或字符串的唯一方法是使用以下命令测试第一个参数is_array()

public function dot($arg1){
   if(is_array($arg1)){
       return implode('.',$arg1);
   }
   else if $arg1 instanceof \Traversable){
       return implode('.',iterator_to_array($arg1));
   }
   else{
       return implode('.',func_get_args());
   }
}

现在你已经处理了你想要的行为，你必须记录它。在php中，由于不允许重载，如果要提供多种类型，约定是使用“mixed”作为类型。

/**
*@param mixed $arg1 an array, iterator that will be joined OR first string of the list
*@return string a string with all strings of the list joined with a point
*@example dot("1","2","3"); returns 1.2.3 dot(array(1,2,3)); returns 1.2.3
*/

此外，根据phpdocumentor 文档，您可以声明某种 valist

/**
*@param string ... list of strings
*/