TP5自定义函数如何写文档

阿辰吖_2334

发布时间：2026-09-11 11:24:08

607人浏览过

来源于php中文网

原创

TP5自定义函数必须加PHPDoc注释，否则IDE无法识别、模板调用报错、团队协作风险高；需严格标注@param类型、@return具体类名及约束说明，确保工具链正常工作。

tp5自定义函数如何写文档

TP5 自定义函数不需要单独写文档，但必须加 PHPDoc 注释，否则 IDE 不识别、模板调用报错、团队协作时没人敢改。

为什么 `common.php` 里的函数必须写 PHPDoc

ThinkPHP5 的模板引擎（如 {$type|getModelFieldType}）在编译时不做类型检查，但 IDE（PHPStorm/VSCode + Intelephense）和静态分析工具（如 PHPStan）依赖 PHPDoc 推导参数类型和返回值。没注释的函数在模板里用 | 调用时，编辑器无法跳转、无参数提示，上线后改错成本翻倍。

不写 @param → 模板传参类型错误时静默失败（比如传字符串却期望整型）
不写 @return → json() 或 show() 类函数返回数组还是 JSON 字符串？控制器里接不住
不写 @deprecated → 老函数还在模板里被调用，没人知道已废弃

`common.php` 函数的标准 PHPDoc 写法

以 show() 为例，不是“写得好看”，而是让工具链能真正工作：

/**
 * 通用 API 响应格式封装
 * @param int $status 业务状态码，1=成功，0=失败
 * @param string $message 提示信息，建议不超过64字符
 * @param array $data 返回数据，支持嵌套数组，不建议超 2MB
 * @param int $httpCode HTTP 状态码，默认200；500/400类需显式传入
 * @return \think\Response 返回 thinkphp 封装的 Response 对象，不可直接 echo
 */
function show($status, $message, $data = [], $httpCode = 200)
{
    return json(['status' => $status, 'message' => $message, 'data' => $data], $httpCode);
}

关键点：

每个 @param 必须带类型，int、string、array 不能省；可选参数要写默认值（如 $data = []）
@return 写具体类名，不是 mixed；TP5 返回的是 \think\Response，不是原生 array
描述里写约束（如“不建议超 2MB”），比“返回数据”这种废话有用得多

模板中调用时最容易忽略的类型陷阱

{$type|getModelFieldType} 表面简单，实际有两层隐式转换：

模板引擎把 $type 当字符串传入函数 → 如果函数期望 int，但没 cast，$arr['2'] 和 $arr[2] 在 PHP 中是不同 key
函数返回值被自动 htmlspecialchars() → 若返回 HTML 片段（如按钮代码），必须加 |raw，否则被转义

所以 getModelFieldType() 正确写法应含类型校验：

/**
 * 根据字段类型编码返回中文名称
 * @param int|string $type 类型编码，支持 '1' 或 1
 * @return string 中文名称，未定义时返回 '未知类型'
 */
function getModelFieldType($type)
{
    $type = (int) $type; // 强制转整型，避免键名错乱
    $arr = [
        1 => '单行文本',
        2 => '单选按钮',
        // ...
    ];
    return $arr[$type] ?? '未知类型';
}