如何使用 PHP 解析 phpDoc 样式的注释块？

Posted 2023-02-21

【中文标题】如何使用 PHP 解析 phpDoc 样式的注释块？

【英文标题】：How to parse a phpDoc style comment block with PHP?

【发布时间】：2011-02-14 12:17:23

【问题描述】：

请考虑以下代码，我试图仅解析文件中的第一个 phpDoc 样式注释（不使用任何其他库）（文件内容放入 $data 变量以进行测试）：

$data = "
/**
 * @file    A lot of info about this file
 *          Could even continue on the next line
 * @author  [e-mail]
 * @version 2010-05-01
 * @todo    do stuff...
 */

/**
 * Comment bij functie bar()
 * @param Array met dingen
 */
function bar($baz) 
  echo $baz;

";

$data =  trim(preg_replace('/\r?\n *\* */', ' ', $data));
preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $data, $matches);
$info = array_combine($matches[1], $matches[2]);
print_r($info)

这几乎可行，除了@todo 之后的所有内容（包括bar() 注释块和代码）被认为是@todo 的值：

Array (
    [file] => A lot of info about this file Could even continue on the next line
    [author] => [e-mail]
    [version] => 2010-05-01
    [todo] => do stuff... /

    /** Comment bij functie bar()
    [param] => Array met dingen /
    function bar() 
      echo ;
    
)

如何更改我的代码以便只解析第一个注释块（换句话说：在遇到第一个“*/”后应该停止解析？

【问题讨论】：

考虑像$s = '/** not a phpDoc @file ... */';这样的字符串放在第一个phpDoc之前的情况。换句话说：使用正则表达式，您将获得 100% 可靠的解决方案。

【参考方案1】：

使用 PCRE 编写解析器会给您带来麻烦。我建议首先依赖tokenizer 或reflection。然后为 doc 块实际实现一个解析器会更安全，它可以处理 phpdoc 格式支持的所有情况（所有库也结束了）。

【讨论】：

感谢您的快速回复。实际上，我必须遍历许多文件，收集每个文件的第一个注释块（只有一个描述文件的注释块；我不需要收集描述函数、方法等的其他注释块。使用标记器的缺点是我不能告诉 token_get_all() 在找到第一个后停止寻找 cmetsblocks。这会导致一个 huge 数组需要大约 20-30 秒才能编译，这太长了，因为我必须在每个页面请求上重新编译（不要问...）。

正则表达式的优点是可以指示它在找到文件的第一个注释块后停止查找，从而获得更好的性能。还是有解决方法（请参阅下面使用标记器的代码）？ foreach ($files as $file) $data = file("$file.inc.php")); $tokens = token_get_all($data); foreach ($tokens as $token) list($id, $text) = $token; switch ($id) case T_DOC_COMMENT: $return[] = $token;休息;默认值：中断； print_r($return);

【参考方案2】：

Php Comment Manager 脚本允许解析 DocBloc cmets 的方法。它支持解析方法描述、@param 和@return 标签。它可以扩展以支持自定义 DocBloc 标签

【讨论】：

您的链接已失效。请问可以更新一下吗？