PHPDoc 中的闭包语法

Question

我在 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);
})

或者是否有可能？

Answer 1

@param callable $callback

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

在您的示例代码中，实际上没有有理由假设您的 changer()

 方法返回 

MyOtherCustomClass()

，因为这纯粹取决于您稍后在 

changer()

 用法中如何编写闭包。最好的情况是，您可以在注释 

at 中表示 changer()

 用法，

changer()

 的这种特定用法返回 

MyOtherCustomClass，因为返回的是该用法的实现，而不是

changer()

实现本身该特定类型的对象。至于记录传递的可调用对象“需要”接受的参数，我想您必须在 param 标记的描述部分中执行此操作。没有语法来描述这种情况。

如果我以这种方式实现某些东西，我会强加一个可调用对象必须全部显式返回的接口，因此我可以写成

changer()

返回该接口。当然，这意味着您的

MyOtherCustomClass

必须实现该接口，但在我看来，这仍然是接近“强制”从

changer()

返回类型的唯一方法。

Answer 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 的函数体不是必需的，所以留空。

1. 使用“Closure”后缀作为类名来澄清它。

Answer 3

/**
 * @param callable(Cls, int, string):MyOtherCustomClass $callback
*/

/**
 * @param Closure(Cls, int, string):MyOtherCustomClass $callback
*/

这里是pslam的参考：

https://psalm.dev/docs/annotating_code/type_syntax/callable_types/