(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 */"
您还可以像这样获取类中已定义方法的文档块定义
<?php
/**
* 这是一个示例类
*/
class Example
{
/**
* 这是一个示例函数
*/
public function fn()
{
// void
}
}
$reflector = new ReflectionClass('Example');
// 获取类文档块
echo $reflector->getDocComment()
// 获取方法文档块
$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);
// 这将输出
数组
(
[0] => 数组
(
[0] => @param int $id 用户 ID
[1] => @throws \Exception 如果用户 ID 不存在
[2] => @return void
)
[1] => 数组
(
[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()); //将打印出方法文档，如预期。
?>