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

Copy
1<?php declare(strict_types=1);
2
3/**
4 * JWT (JSON Web Token) をパースし、ヘッダー、ペイロード、署名および署名検証の結果を返します。
5 * システムエンジニアを目指す初心者の方にも理解しやすいように、基本的なJWTの構造とパース方法を示します。
6 *
7 * @param string      $jwt    パースするJWT文字列。
8 * @param string|null $secret 署名検証に使用するシークレットキー (HMACの場合)。
9 *                            提供されない場合、または対応していないアルゴリズムの場合、署名検証は行われません。
10 * @return array|null ヘッダー、ペイロード、署名、署名検証結果を含む連想配列。JWT形式が無効な場合はnull。
11 */
12function parseJwtToken(string $jwt, ?string $secret = null): ?array
13{
14    // JWTは「ヘッダー.ペイロード.署名」の3つの部分で構成されます。
15    $parts = explode('.', $jwt);
16
17    if (count($parts) !== 3) {
18        // JWTの形式が正しくありません。
19        return null;
20    }
21
22    // 各部分を分解します。
23    list($encodedHeader, $encodedPayload, $encodedSignature) = $parts;
24
25    // ヘッダーとペイロードはBase64 URLエンコードされており、さらにJSON形式です。
26    // まずBase64 URLデコードを行い、次にJSONデコードを行います。
27    // Base64 URLデコードは、通常のBase64と異なり、URLセーフな文字を使用します。
28    $header = json_decode(base64UrlDecode($encodedHeader), true);
29    $payload = json_decode(base64UrlDecode($encodedPayload), true);
30
31    if ($header === null || $payload === null) {
32        // ヘッダーまたはペイロードのデコードに失敗しました。
33        return null;
34    }
35
36    $isValidSignature = false; // 署名検証結果の初期値
37
38    // シークレットキーが提供されている場合、署名を検証します。
39    if ($secret !== null) {
40        // ヘッダーから署名アルゴリズム (alg) を取得します。
41        $alg = $header['alg'] ?? null;
42
43        // このサンプルでは、HMAC SHA256 (HS256) アルゴリズムのみをサポートします。
44        // 他のアルゴリズム（例: RSA）は、より複雑な公開鍵暗号の知識と実装が必要です。
45        if ($alg === 'HS256') {
46            // 期待される署名を計算します。署名は「エンコードされたヘッダー.エンコードされたペイロード」とシークレットキーから生成されます。
47            $expectedSignature = base64UrlEncode(hash_hmac('sha256', "$encodedHeader.$encodedPayload", $secret, true));
48            // 計算した署名と、JWTに含まれる実際の署名を比較して検証します。
49            // hash_equals() はタイミング攻撃を防ぐために安全な比較を行います。
50            $isValidSignature = hash_equals($expectedSignature, $encodedSignature);
51        } else {
52            // 未対応のアルゴリズムの場合、署名検証は行われず、結果は偽 (false) となります。
53            $isValidSignature = false;
54        }
55    } else {
56        // シークレットキーが提供されていない場合、署名検証は行われないため、結果は偽 (false) となります。
57        // これは、JWTの信頼性を確保するためには署名検証が必須であるためです。
58        $isValidSignature = false;
59    }
60
61    // パース結果を連想配列として返します。
62    return [
63        'header' => $header,
64        'payload' => $payload,
65        'signature' => $encodedSignature,
66        'isValidSignature' => $isValidSignature,
67    ];
68}
69
70/**
71 * Base64 URLエンコードされた文字列をデコードします。
72 * JWTではURLセーフなBase64エンコーディングが使用されるため、通常のBase64デコードとは処理が異なります。
73 *
74 * @param string $data Base64 URLエンコードされた文字列。
75 * @return string デコードされた文字列。デコードに失敗した場合は空文字列。
76 */
77function base64UrlDecode(string $data): string
78{
79    // JWTのBase64 URLエンコーディングは、標準のBase64とは異なる文字セット('-'と'_')を使用し、パディング文字'='が省略されます。
80    // そのため、まずURLセーフな文字を標準Base64の文字に変換し、base64_decode()でデコードします。
81    // base64_decodeのstrictモード(true)で不正な文字があるとfalseを返すため、そのチェックが必要です。
82    $decoded = base64_decode(str_replace(['-', '_'], ['+', '/'], $data), true);
83    return $decoded !== false ? $decoded : '';
84}
85
86/**
87 * 文字列をBase64 URLエンコードします。
88 * JWTの署名計算時に、ヘッダーとペイロードをエンコードする際に使用されます。
89 *
90 * @param string $data エンコードする文字列。
91 * @return string Base64 URLエンコードされた文字列。
92 */
93function base64UrlEncode(string $data): string
94{
95    // 標準Base64エンコード後、URLセーフな文字('-'と'_')に変換し、末尾のパディング文字'='を削除します。
96    $encoded = strtr(base64_encode($data), '+/', '-_');
97    return rtrim($encoded, '=');
98}
99
100// --- 使用例 ---
101// このJWTトークンは、オンラインツール (例: https://jwt.io/) で以下の情報を使用して生成できます:
102// ヘッダー: {"alg":"HS256","typ":"JWT"}
103// ペイロード: {"sub":"1234567890","name":"John Doe","iat":1516239022, "role":"user"}
104// シークレットキー: 'your-secret-key'
105$sampleJwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJyb2xlIjoidXNlciJ9.Kj3K8U84m4fGg431z7h4d_K5H7qW7f7Q6o7_G7_K7";
106$secretKey = "your-secret-key"; // JWT生成時に使用したシークレットキーを指定してください。
107
108echo "--- JWTトークンのパースと署名検証の例 ---" . PHP_EOL;
109
110// 署名検証を含むパース
111$parsedToken = parseJwtToken($sampleJwt, $secretKey);
112
113if ($parsedToken) {
114    echo "■ パース結果" . PHP_EOL;
115    echo "  ヘッダー: " . json_encode($parsedToken['header'], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . PHP_EOL;
116    echo "  ペイロード: " . json_encode($parsedToken['payload'], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . PHP_EOL;
117    echo "  署名: " . $parsedToken['signature'] . PHP_EOL;
118    echo "  署名検証結果: " . ($parsedToken['isValidSignature'] ? '有効 (Yes)' : '無効または未検証 (No)') . PHP_EOL;
119} else {
120    echo "JWTトークンのパースに失敗しました。" . PHP_EOL;
121}
122
123echo PHP_EOL . "--- シークレットキーなしでパースする例 (署名検証は行われない) ---" . PHP_EOL;
124
125$parsedNoSecret = parseJwtToken($sampleJwt); // シークレットキーを渡さない
126
127if ($parsedNoSecret) {
128    echo "■ パース結果 (シークレットキーなし)" . PHP_EOL;
129    echo "  ペイロード: " . json_encode($parsedNoSecret['payload'], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . PHP_EOL;
130    echo "  署名検証結果: " . ($parsedNoSecret['isValidSignature'] ? '有効 (Yes)' : '無効または未検証 (No)') . PHP_EOL; // false が期待されます
131} else {
132    echo "JWTトークンのパースに失敗しました。" . PHP_EOL;
133}
134
135echo PHP_EOL . "--- 誤ったシークレットキーでパースする例 (署名検証は失敗する) ---" . PHP_EOL;
136
137$wrongSecretKey = "wrong-secret"; // 正しいシークレットキーではない
138$parsedWrongSecret = parseJwtToken($sampleJwt, $wrongSecretKey);
139
140if ($parsedWrongSecret) {
141    echo "■ パース結果 (誤ったシークレットキー)" . PHP_EOL;
142    echo "  ペイロード: " . json_encode($parsedWrongSecret['payload'], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . PHP_EOL;
143    echo "  署名検証結果: " . ($parsedWrongSecret['isValidSignature'] ? '有効 (Yes)' : '無効または未検証 (No)') . PHP_EOL; // false が期待されます
144} else {
145    echo "JWTトークンのパースに失敗しました。" . PHP_EOL;
146}
147
148echo PHP_EOL . "--- 不正なJWT構造の例 ---" . PHP_EOL;
149
150$invalidJwtStructure = "invalid.jwt"; // 「.」が2つしかないため、3つの部分に分割できない
151$parsedInvalidStructure = parseJwtToken($invalidJwtStructure, $secretKey);
152
153if ($parsedInvalidStructure) {
154    echo "不正な構造のJWTがパースされました (予期せぬ結果)。" . PHP_EOL;
155} else {
156    echo "不正なJWT構造のため、パースに失敗しました (期待通りの結果)。" . PHP_EOL;
157}

このサンプルコードは、PHPでJWT（JSON Web Token）を解析し、その内容を取り出して署名を検証する方法を示しています。JWTは「ヘッダー」「ペイロード」「署名」の3つの部分から構成されており、ウェブアプリケーションの認証や認可によく利用されます。

メインの関数であるparseJwtTokenは、引数としてパースするJWT文字列（$jwt）を受け取ります。オプションで署名検証に使うシークレットキー（$secret）を指定できます。この関数は、まずJWTを3つの部分に分割し、ヘッダーとペイロードをBase64 URLデコードとJSONデコードによって元のデータ形式に戻します。

もしシークレットキーが提供されている場合、指定されたアルゴリズム（このコードではHMAC SHA256のみ対応）に基づいて署名を再計算し、元の署名と照合することで、JWTが改ざんされていないか、発行者によって信頼できるものであるかを検証します。この検証結果はisValidSignatureという真偽値で返されます。

関数が成功すると、デコードされたヘッダーとペイロード、元の署名、そして署名検証結果を含む連想配列を戻り値として返します。JWTの形式が正しくない場合やデコードに失敗した場合はnullを返します。

補助関数としてbase64UrlDecodeとbase64UrlEncodeが用意されており、これらはJWT特有のURLセーフなBase64エンコード・デコード処理を行います。システムエンジニアにとって、JWTの仕組みを理解し、そのパースと署名検証の実装方法を知ることは、セキュリティを考慮したシステム開発において非常に重要です。

Copy
1<?php
2
3/**
4 * PHPコードをトークンに分解し、その情報を表示する関数。
5 * システムエンジニアを目指す初心者向けに、PHPコードの内部構造を理解する一助となります。
6 * この関数は、PHPの標準トークナイザー機能である `token_get_all()` を使用します。
7 *
8 * @param string $phpCode 解析するPHPコード文字列
9 * @return void
10 */
11function analyzePhpCodeTokens(string $phpCode): void
12{
13    // token_get_all() はPHPコードを個々のトークンに分解します。
14    // 各トークンは、配列（ID, 文字列値, 行番号）または単一の文字（オペレータなど）として返されます。
15    $tokens = token_get_all($phpCode);
16
17    echo "--- PHP Code Token Analysis ---" . PHP_EOL;
18    foreach ($tokens as $token) {
19        if (is_array($token)) {
20            // トークンが配列の場合 (例: T_STRING, T_VARIABLE, T_OPEN_TAG)
21            // token_name() はトークンIDに対応する名前を返します (例: 1000 -> T_STRING)。
22            echo sprintf(
23                "Line %-4d: %-25s (ID: %-5d) -> '%s'%s",
24                $token[2],                       // 行番号
25                token_name($token[0]),          // トークン名 (例: T_CLASS)
26                $token[0],                       // トークンID (例: T_CLASS の数値ID)
27                str_replace(PHP_EOL, '\\n', $token[1]), // トークン文字列 (改行は表示用にエスケープ)
28                PHP_EOL
29            );
30        } else {
31            // トークンが単一の文字の場合 (例: '{', ';', '=')
32            echo sprintf(
33                "Line %-4s: %-25s (ID: %-5s) -> '%s'%s",
34                '-',                             // 行番号は不明または不特定
35                "PUNCTUATION / OPERATOR",        // 句読点や演算子
36                '-',                             // IDはなし
37                str_replace(PHP_EOL, '\\n', $token), // トークン文字
38                PHP_EOL
39            );
40        }
41    }
42    echo "------------------------------" . PHP_EOL;
43}
44
45// 解析するサンプルPHPコードを定義
46$sampleCode = <<<'EOT'
47<?php
48/**
49 * Sample PHP Code for Token Analysis.
50 */
51namespace MyProject;
52
53class ExampleClass
54{
55    public const STATUS_ACTIVE = 1; // クラス定数
56
57    private string $name;
58
59    public function __construct(string $name)
60    {
61        $this->name = $name;
62    }
63
64    public function greet(): string
65    {
66        return "Hello, " . $this->name . "!";
67    }
68}
69
70$obj = new ExampleClass("World");
71echo $obj->greet(); // メソッド呼び出し
72EOT;
73
74// 関数を実行し、PHPコードのトークン解析の結果を表示
75analyzePhpCodeTokens($sampleCode);

このサンプルコードは、PHPコードがどのように構成されているかを理解するため、コードを「トークン」という最小単位に分解して表示します。analyzePhpCodeTokens関数は、解析したいPHPコードの文字列を引数として受け取り、分解されたトークン情報を画面に出力します。この関数には戻り値がありません。

関数内部では、PHPの標準機能であるtoken_get_all()を使用しています。この関数は、指定されたPHPコードを構文要素ごとに区切り、それぞれのトークンを配列として返します。各トークン配列には、その種類を示すID、実際の文字列表現、コード中の行番号が含まれます。例えば、キーワードや変数名などは「T_STRING」や「T_CLASS」といったトークン名で識別でき、これらの名前はtoken_name()関数を使ってIDから取得できます。句読点や演算子などは単一の文字として扱われます。

提供されたリファレンス情報にあるTOKEN_PARSEは、PHPがコードを解析する過程で内部的に用いられる可能性のあるトークンID定数の一つです。これは直接コードで操作するものではなく、PHPのパーサーが構文を理解する上で参照する多くの定数の一つとして存在します。このサンプルを通して、PHPがコードをどのように処理しているかの基本的な仕組みを学ぶことができます。