PHP闭包需通过变量或参数的PHPDoc注释标注类型，如@var callable(int, string): bool或@param callable(int, array): void，不可直接注释闭包定义；封装时须确保类型信息不丢失。
PHP 闭包的 PHPDoc 注释写法
PHP 闭包本身不是类、方法或函数，不能直接在定义处用 /** */ 块注释绑定到它身上——PHP 解析器不识别这种写法。真正有效的注释方式，是给**接收闭包的变量或参数**添加类型提示和文档注释。
给闭包变量加 PHPDoc 类型注释
当把闭包赋值给变量时，用 @var 明确标注其签名，这是最常用也最可靠的写法。IDE（如 PhpStorm）和静态分析工具（如 PHPStan）都依赖这个信息做类型推导。
/** @var callable(int, string): bool $validator */
$validator = function (int $id, string $name): bool {
return $id > 0 && !empty($name);
};-
callable(int, string): bool表示该闭包接受两个参数（int和string），返回bool - 参数名（
$id,$name）在注释中可省略，但加上更利于阅读和 IDE 提示 - 如果闭包使用了
use引入外部变量，PHPDoc 不体现这些变量，需靠上下文理解
为函数/方法参数中的闭包写 PHPDoc
在定义接收闭包的函数时，必须在参数前用 @param 注释清楚闭包的签名，否则调用方无法获知期望结构，也容易传错类型。
/** * @param callable(int, array): void $callback */ function processItems(array $items, callable $callback): void { foreach ($items as $index => $item) { $callback($index, [$item]); } }
-
callable(int, array比只写): void callable精确得多，能触发 IDE 参数提示和错误检查 - 嵌套类型如
array或array都支持，PHPStan 和 Psalm 能据此验证实际调用 - 不要写成
@param function(int, string): bool $callback——function不是合法的 PHPDoc 类型关键字，应始终用callable
封装闭包时避免的典型错误
封装常用于工厂、配置或策略模式，这时闭包往往被包装进数组、对象属性或返回值中。最容易忽略的是：**封装层本身不带类型信息，会导致下游丢失闭包契约**。
立即学习“PHP免费学习笔记（深入）”；
// ❌ 错误：封装后类型丢失
$config['on_error'] = function (string $msg): void { error_log($msg); };
// ✅ 正确：用带类型的变量承接，再赋值
/* @var callable(string): void $onError /
$onError = function (string $msg): void { error_log($msg); };
$config['on_error'] = $onError;
- 直接往数组里塞闭包，PHPDoc 无法附着，IDE 和静态分析完全“看不见”它的签名
- 即使封装进对象属性，也要在属性上加
@var注释，例如：/** @var callable(): array */ public $loader; - 返回闭包的函数，必须用
@return callable(...): ...明确标注，否则调用方拿到的是模糊的callable
闭包的可维护性高度依赖 PHPDoc 的准确性，而不是语法糖或注释位置——少一个参数类型，就可能让下游多出三次调试。
