(PHP 5, PHP 7, PHP 8)
ReflectionClass::getDocComment — 获取文档注释
从类中获取文档注释。文档注释以 /** 开头，后面是空格。如果类定义上方有多个文档注释，则将采用最靠近类的那个注释。
此函数没有参数。
如果存在则为文档注释，否则为 false。
示例 #1 ReflectionClass::getDocComment() 示例
<?php
/**
* 一个测试类
*
* @param foo bar
* @return baz
*/
class TestClass { }
$rc = new ReflectionClass('TestClass');
var_dump($rc->getDocComment());
?>上面的示例将输出
string(61) "/** * A test class * * @param foo bar * @return baz */"
您还可以以这种方式获取类定义的已定义方法的 docblock 定义
<?php
/**
* 这是一个示例类
*/
class Example
{
/**
* 这是一个示例函数
*/
public function fn()
{
// void
}
}
$reflector = new ReflectionClass('Example');
// 获取类 DocBlock
echo $reflector->getDocComment()
// 获取方法 DocBlock
$reflector->getMethod('fn')->getDocComment();
?>根据我在 PHP (5.3.2) 源代码中找到的内容，getDocComment 将按解析器发现的方式返回文档注释。
文档注释 (T_DOC_COMMENT) 必须以 /** 开头 - 这是两个星号，而不是一个。注释将一直持续到第一个 */。普通的多行注释 /*...*/ (T_COMMENT) 不算作文档注释。
文档注释本身包含这五个字符，所以 <?php substr($doccomment, 3, -2) ?> 将为您获取其中的内容。建议在调用后使用 trim()。如果您使用的是像 eAccelerator 这样的字节码缓存，即使存在格式正确的 Docblock，此方法也会返回 FALSE。看起来此方法所需的信息会被字节码缓存剥离。此代码可以帮助您以数组格式获取 docBlock 的内容，从 @ 符号开始，并忽略 (*) 星号。
class Home {
/**
* 此方法加载主页
* @param int $id 用户 ID
* @throws \Exception 如果用户 ID 不存在
* @return void
*/
public function index( $id)
{
#...您的代码在这里
}
}
$object = new Home();
// 获取注释字符串
$comment_string= (new ReflectionClass($object))->getMethod('index')->getdoccomment();
// 定义用于字符串匹配的正则表达式模式
$pattern = "#(@[a-zA-Z]+\s*[a-zA-Z0-9, ()_].*)#";
// 在提供的字符串上执行正则表达式
preg_match_all($pattern, $comment_string, $matches, PREG_PATTERN_ORDER);
echo "<pre>"; print_r($matches);
// 这将输出
Array
(
[0] => Array
(
[0] => @param int $id 用户 ID
[1] => @throws \Exception 如果用户 ID 不存在
[2] => @return void
)
[1] => Array
(
[0] => @param int $id 用户 ID
[1] => @throws \Exception 如果用户 ID 不存在
[2] => @return void
)
)
// 您之后可以通过索引访问特定的字符串值请注意，文档注释的处理方式与 PHP 和 OpCache 中的普通注释不同。
文档注释实际上由 OpCache 保留，并且可以通过此反射 API 访问，除非被 "opcache.save_comments" INI 指令禁用，请参见 https://php.net/manual/en/opcache.configuration.php#ini.opcache.save-comments请注意，\ReflectionClass::getDocComment() 会忽略所有其他 PHP 代码以及最后遇到的 T_DOC_COMMENT 和类/元素定义之间的所有空格。
唯一的例外似乎是 T_NAMESPACE 声明和 T_FUNCTION 定义。
<?php
/**
* 命名空间之前。
*/
namespace Foo;
/**
* 命名空间之后。
*/
// ^^ 包含过多的前导 + 尾随空格。
use Bar\Baz;
const FOO = 'BAR';
$ns = 'bar';
# function foo() {}
$a = 2 + 1;
#/** what? */
// ^^ 单行 T_DOC_COMMENT 在注释掉时不可见。
count(array());
class Foo {
}
$reflector = new \ReflectionClass('Foo\Foo');
var_dump($reflector->getDocComment());
?>
产生，尽管中间有所有垃圾
string(28) "/**
* 命名空间之后。
*/"
总结
1. 如果有多个文档注释，则最后一个遇到的注释将适用。
2. 删除 "命名空间之后。" 文档注释将产生 FALSE。
(命名空间限定了作用域。)
3. 取消注释函数定义将产生 FALSE。
(文档注释适用于函数，而不是类。)
4. 尽管 "const" 常量声明是自己的语言结构，但它不会限定作用域。
5. T_DOC_COMMENT ("/**...*/") 前后任何前导和尾随空格都将被忽略，但其中的整个字符串内容（包括所有空格）将按字面意义/逐字地使用。
[PHP 5.4.29]不仅此方法可以通过类的给定方法名称找到文档，例如
<?php
class Foo{
/**
* 方法描述
*/
function bar(){
/** 代码在此... */
}
}
$ref = new ReflectionClass('Foo');
print_r($ref->getMethod('bar')->getDocComment()); // 会输出方法文档
?>
但是，如果在定义中没有方法文档，并且类继承自其他类，程序会自动
尝试从父类中查找文档，例如：
<?php
class Foo2 extends Foo{}
$ref = new ReflectionClass('Foo');
print_r($ref->getMethod('bar')->getDocComment()); // 会输出方法文档
?>