PHPDoc 中的闭包语法

Posted 2023-02-22

【中文标题】PHPDoc 中的闭包语法

【英文标题】：Syntax of Closure in PHPDoc

【发布时间】：2013-05-11 11:48:28

【问题描述】：

我在 phpDoc 中找不到任何关于 Closure 类型的文档。所以我的问题是如何定义发送给闭包的参数的参数及其返回值？

例子：

我如何描述“回调”将获得一个“MyCustomClass”、一个数字和一个字符串，并返回一个“MyOtherCustomClass”？

/**
 * @param MyCustomClass $cls
 * @param Closure       $callback this isn't really explaining what this is
 *
 * @return MyOtherCustomClass
 */
function changer($cls, $callback)

  return $callback($cls, 2, "a string");


changer($aCustomeClass, function($cls, $int, $string)
   return new MyOtherCustomClass($cls, $int, $string);
)

或者如果可能的话？

【问题讨论】：

我认为没有合理的方式在注释中描述它。即使在 PHP 手册中，它们也只是在参数描述中引用为 callable。

这就是我所担心的，但如果可能的话，那就太好了。

“深度闭包定义”讨论：github.com/phpDocumentor/phpDocumentor2/issues/830

【参考方案1】：

@param callable $callback 确实是用于该部分的语法。您并没有将该参数限制为闭包本身......传递给它的任何可调用对象都将在该实现中被接受。 Callable 是合法的“PHP 类型”，因此 phpDocumentor 接受它作为有效的类型。

在您的示例代码中，实际上没有理由假设您的 changer() 方法返回 MyOtherCustomClass()，因为这完全取决于您稍后在 @987654324 中如何编写闭包@ 用法。充其量，您可以在评论中at 指出changer() 的用法changer() 的这种特殊用法返回MyOtherCustomClass，因为它是该用法的实现，不是 changer() 实现本身，它返回特定类型的对象。

至于记录传递的可调用对象是“必需”接受的参数，我想你必须在 param 标记的描述部分中这样做。没有语法来描述这种情况。

如果我要以这种方式实现某些东西，我将强加一个接口，所有可调用对象都必须显式返回，因此我可以写 changer() 返回该接口。当然，这意味着您的MyOtherCustomClass 必须实现该接口，但在我看来，这仍然是接近“强制”来自changer() 的返回类型的唯一方法。

【讨论】：

如果我重写代码，一个接口可以解决问题。就我而言，这不是一个选择。

确实，代码重写可能是一种限制 ;-) 我发现考虑我排除的选项有时仍然可以产生其他新想法，所以我倾向于提到这些事情在思考某人的问题时对我说。

给你检查标记......虽然不适用于我目前的项目，但它通常是解决问题的方法:)

【参考方案2】：

使用间接技巧

您的代码：

/**
 * @param MyCustomClass  $cls
 * @param MyFancyClosure $callback
 *
 * @return MyOtherCustomClass
 */
function changer($cls, $callback)
    return $callback($cls, 2, "a string");


changer($aCustomeClass, function($cls, $int, $string)
   return new MyOtherCustomClass($cls, $int, $string);
)

然后在某处提供一个虚拟代码：

/**
 * this is awesome closure!
 */
class MyFancyClosure 
    /**
     * @param MyCustomClass $cls
     * @param int           $int
     * @param string        $str
     *
     * @return MyOtherCustomClass
     */
    public function __invoke($cls, $int, $str) 

注意：

__invoke 的函数体不是必需的，所以留空。 使用“Closure”后缀作为类名来阐明它。