(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 保留的，並且可以透過這個 reflection API 存取，除非被 "opcache.save_comments" INI 指令停用，請參閱 https://php.dev.org.tw/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;
#/** 什麼？ */
// ^^ 單行 T_DOC_COMMENT 在被註釋掉時是不可見的。
count(array());
class Foo {
}
$reflector = new \ReflectionClass('Foo\Foo');
var_dump($reflector->getDocComment());
?>
儘管中間有很多雜項程式碼，但仍會產生以下結果
字串(28) "/**
* 命名空間之後。
*/"
總結
1. 如果有多個文件註釋，則最後遇到的那個會生效。
2. 移除「After namespace」區塊註解會回傳 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()); //會如預期印出方法的區塊註解。
?>