【PHP8.x】T_DOC_COMMENT定数の使い方

Copy
1<?php
2
3/**
4 * PHPコードをトークンに分解し、特にPHPDocコメント (T_DOC_COMMENT) を識別する関数。
5 *
6 * この関数は、システムエンジニアを目指す初心者がPHPの内部的な字句解析と、
7 * PHPDocコメントがどのように識別されるかを理解するのに役立ちます。
8 *
9 * @param string $phpCode 解析対象のPHPコード文字列
10 * @return void
11 */
12function analyzePhpDocComments(string $phpCode): void
13{
14    echo "--- PHPコードトークン解析 ---\n";
15
16    // token_get_all() 関数は、指定されたPHPコードをPHPエンジンが認識するトークンに分解します。
17    // 各トークンは配列、または単一の文字（演算子など）です。
18    // 配列の場合：[0 => トークンID (int), 1 => トークンの値 (string), 2 => 行番号 (int)]
19    $tokens = token_get_all($phpCode);
20
21    foreach ($tokens as $token) {
22        if (is_array($token)) {
23            // トークンが配列の場合、トークンID、値、行番号が含まれています。
24            $tokenId = $token[0];      // トークンID (例: T_DOC_COMMENT, T_FUNCTION)
25            $tokenValue = $token[1];   // トークンの実際の文字列 (例: "/** ... */", "function")
26            $lineNumber = $token[2];   // コード中の行番号
27
28            // token_name() 関数はトークンIDに対応する定数名 (例: "T_DOC_COMMENT") を返します。
29            $tokenName = token_name($tokenId);
30
31            // T_DOC_COMMENT 定数を使って、PHPDoc形式のコメントを識別します。
32            if ($tokenId === T_DOC_COMMENT) {
33                echo "[行: {$lineNumber}] [トークン名: {$tokenName}] (PHPDocコメント)\n";
34                echo "  値: '{$tokenValue}'\n";
35            } elseif ($tokenId === T_COMMENT) {
36                // 通常のコメント (// または /* ... */) は T_COMMENT として識別されます。
37                echo "[行: {$lineNumber}] [トークン名: {$tokenName}] (通常のコメント)\n";
38                echo "  値: '{$tokenValue}'\n";
39            } else {
40                // その他のトークンも表示して、コードの全体像を把握しやすくします。
41                // echo "[行: {$lineNumber}] [トークン名: {$tokenName}]\n";
42                // echo "  値: '{$tokenValue}'\n";
43            }
44        } else {
45            // 配列ではないトークンは、通常、単一の演算子や区切り文字（例: "{", ";", "="）です。
46            // echo "[文字トークン] '{$token}'\n";
47        }
48    }
49    echo "--------------------------\n";
50}
51
52// T_DOC_COMMENT 定数によって識別されるPHPDocコメントを含むPHPコードの例
53$sampleCode = <<<'EOD'
54<?php
55
56/**
57 * これは関数の目的を説明するPHPDocコメントの例です。
58 * T_DOC_COMMENT 定数により、このブロックがPHPドキュメントコメントであると識別されます。
59 *
60 * @param string $name ユーザーの名前
61 * @return string 挨拶のメッセージ
62 */
63function greetUser(string $name): string
64{
65    // これは通常の1行コメントです。T_COMMENT として識別されます。
66    return "こんにちは、" . $name . "さん！";
67}
68
69/*
70 * これはブロックコメントの例です。
71 * T_COMMENT として識別され、T_DOC_COMMENT とは異なります。
72 */
73$message = greetUser("PHP開発者");
74echo $message . "\n";
75
76?>
77EOD;
78
79// サンプルコードを解析し、PHPDocコメントを識別します。
80analyzePhpDocComments($sampleCode);

T_DOC_COMMENTは、PHPコード内の「PHPDoc」と呼ばれる特別な形式のコメントを識別するための定数です。PHPバージョン8以降で利用でき、この定数自体は整数値を返します。

このサンプルコードでは、analyzePhpDocComments関数がPHPの内部的な仕組みである字句解析をデモンストレーションしています。引数としてPHPコード文字列（$phpCode）を受け取り、それをPHPエンジンが認識する小さな「トークン」と呼ばれる部品に分解します。この関数は解析結果を画面に出力するため、具体的な戻り値はありません（void）。

分解されたトークンの中には、プログラムの命令だけでなく、コメントも含まれます。token_get_all()関数によって得られたトークンを一つずつ確認し、T_DOC_COMMENTという定数と一致するトークンIDを持つものをPHPDocコメントとして識別しています。通常の//や/* ... */形式のコメントはT_COMMENTとして区別され、PHPDocコメントとは異なることが理解できます。このように、PHPがコード内のコメントの種類をどのように区別しているかを、このコードを通じて学ぶことができます。

Copy
1<?php
2
3/**
4 * PHPコード内のドキュメントコメント (T_DOC_COMMENT) を抽出する関数。
5 *
6 * T_DOC_COMMENT は、`/** ... */` 形式のドキュメントコメントを表すPHPのトークン定数です。
7 * この関数は、`token_get_all()` を使用してPHPコードをトークンに分解し、
8 * ドキュメントコメントを見つけてその内容を表示します。
9 *
10 * @param string $phpCode 解析するPHPコード文字列
11 */
12function demonstrateTDocComment(string $phpCode): void
13{
14    echo "--- 解析対象のPHPコード ---" . PHP_EOL;
15    echo $phpCode . PHP_EOL;
16    echo "--------------------------" . PHP_EOL . PHP_EOL;
17
18    // token_get_all() 関数はPHPコードを配列のトークンに分解します。
19    // 各トークンは、[トークンID, トークン文字列, 行番号] の形式の配列、
20    // または単一文字のトークン（例: '{', ';') の場合は文字列として返されます。
21    $tokens = token_get_all($phpCode);
22
23    echo "--- 検出された T_DOC_COMMENT ---" . PHP_EOL;
24    $foundDocComment = false;
25
26    foreach ($tokens as $token) {
27        // トークンが配列であり、そのトークンIDが T_DOC_COMMENT であるかをチェックします。
28        if (is_array($token) && $token[0] === T_DOC_COMMENT) {
29            // T_DOC_COMMENT が見つかった場合、その内容と行番号を表示します。
30            echo "内容: " . $token[1] . " (行: " . $token[2] . ")" . PHP_EOL;
31            $foundDocComment = true;
32        }
33    }
34
35    if (!$foundDocComment) {
36        echo "T_DOC_COMMENT は見つかりませんでした。" . PHP_EOL;
37    }
38    echo "----------------------------------" . PHP_EOL;
39}
40
41// サンプルとして解析するPHPコードを用意します。
42$samplePhpCode = <<<'EOD'
43<?php
44
45/**
46 * これはクラスレベルのドキュメントコメントです。
47 * クラスの目的や使い方を記述します。
48 *
49 * @package App
50 * @author Your Name <your.email@example.com>
51 */
52class MySampleClass
53{
54    /**
55     * これはプロパティのドキュメントコメントです。
56     * プロパティの役割を説明します。
57     *
58     * @var string
59     */
60    public string $name = 'Default';
61
62    /**
63     * これはメソッドのドキュメントコメントです。
64     * メソッドの機能、引数、戻り値について記述します。
65     *
66     * @param string $message 表示するメッセージ
67     * @return void
68     */
69    public function greet(string $message): void
70    {
71        echo "Hello, " . $message . PHP_EOL;
72    }
73}
74
75/**
76 * もう一つのドキュメントコメントです。
77 *
78 * @deprecated 1.0.0 This function is no longer recommended.
79 */
80function oldFunction(): void
81{
82    // これは通常の行コメントです。
83}
84
85/*
86 * これはブロックコメントであり、T_DOC_COMMENT とは異なります。
87 */
88EOD;
89
90// 上記のPHPコードに対して関数を実行し、T_DOC_COMMENT を検出します。
91demonstrateTDocComment($samplePhpCode);

T_DOC_COMMENTは、PHP 8で提供される拡張機能の定数の一つです。これは整数値を持ち、PHPのソースコード内で記述される/** ... */形式のドキュメントコメントを識別するためのトークンIDとして利用されます。この定数自体には引数はなく、常に整数型の値を返します。

サンプルコードでは、このT_DOC_COMMENT定数の具体的な使用方法を実演しています。まず、token_get_all()関数を使って、引数として渡されたPHPコード文字列を、PHPが認識する最小単位である「トークン」の配列に分解します。次に、このトークン配列を一つずつ走査し、各トークンが配列形式であり、そのトークンIDがT_DOC_COMMENTと一致するかどうかを判断します。

T_DOC_COMMENTとして識別された場合、そのトークンの内容（つまり、/** ... */で囲まれた実際のコメント文字列）と、それがコード内のどの行に存在するかという情報が抽出され、出力されます。これにより、プログラマが記述したクラス、プロパティ、メソッドなどの説明となるドキュメントコメントのみを効率的に検出し、解析することが可能になります。なお、//による一行コメントや/* ... */による複数行ブロックコメントは、T_DOC_COMMENTとは異なるトークンとして扱われるため、この定数では検出されません。