【PHP8.x】xml_set_notation_decl_handler()関数の使い方

Copy
1<?php
2
3/**
4 * XMLパーサがNOTATION宣言を検出したときに呼び出されるハンドラ関数。
5 *
6 * XMLのDTD内で定義されたNOTATION宣言を処理します。
7 * NOTATIONは、XML文書内で参照される外部の非XMLデータを記述するために使用されます。
8 * 例: 画像ファイル形式(GIF, JPEG)などをXML内で示す。
9 *
10 * @param XMLParser $parser      XMLパーサのリソース。
11 * @param string    $notationName NOTATIONの名前。
12 * @param string    $base        基準URI。現在のPHPの実装では通常空文字列。
13 * @param string    $systemId    システムの識別子（URI）。
14 * @param string|null $publicId   公開識別子（省略可能）。
15 */
16function notationDeclHandler(
17    XMLParser $parser,
18    string $notationName,
19    string $base,
20    string $systemId,
21    ?string $publicId
22): void {
23    echo "--- NOTATION 宣言を検出しました ---" . PHP_EOL;
24    echo "  NOTATION名: " . $notationName . PHP_EOL;
25    echo "  システムID: " . $systemId . PHP_EOL;
26    echo "  公開ID: " . ($publicId ?? 'なし') . PHP_EOL;
27    echo "  (ベースURI: " . ($base ?: 'なし') . ")" . PHP_EOL; // PHPでは通常空
28    echo "------------------------------------" . PHP_EOL;
29}
30
31// 1. XMLパーサを作成します。
32// xml_parser_create() は新しいXMLパーサを作成し、そのハンドルを返します。
33$parser = xml_parser_create();
34
35// 2. XMLパーサにNOTATION宣言ハンドラを設定します。
36// xml_set_notation_decl_handler() は、DTD内のNOTATION宣言が検出されたときに
37// 呼び出される関数を登録します。
38xml_set_notation_decl_handler($parser, 'notationDeclHandler');
39
40// 3. パースするXMLデータを用意します。
41// ここでは、内部DTDサブセットに2つのNOTATION宣言 (gif, jpeg) と
42// 1つの公開識別子を持つNOTATION宣言 (txt) を含むXMLを作成します。
43$xmlData = <<<XML
44<?xml version="1.0" encoding="UTF-8"?>
45<!DOCTYPE document [
46  <!-- NOTATION宣言: 'gif'という名前で、システムID 'image/gif' を持つ -->
47  <!NOTATION gif SYSTEM "image/gif">
48  <!-- NOTATION宣言: 'jpeg'という名前で、システムID 'image/jpeg' を持つ -->
49  <!NOTATION jpeg SYSTEM "image/jpeg">
50  <!-- NOTATION宣言: 'txt'という名前で、公開IDとシステムIDを持つ -->
51  <!NOTATION txt PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
52  <!-- 要素宣言（必須ではないが、整形式のために追加） -->
53  <!ELEMENT document EMPTY>
54]>
55<document/>
56XML;
57
58// 4. XMLデータをパースします。
59// xml_parse() は提供されたXMLデータを解析し、設定されたハンドラ関数を呼び出します。
60if (!xml_parse($parser, $xmlData)) {
61    // パース中にエラーが発生した場合、エラー情報を表示します。
62    $errorCode = xml_get_error_code($parser);
63    $errorString = xml_error_string($errorCode);
64    $line = xml_get_current_line_number($parser);
65    echo "XMLパースエラー: {$errorString} (コード: {$errorCode}) at line {$line}" . PHP_EOL;
66} else {
67    echo "XMLパースが完了しました。" . PHP_EOL;
68}
69
70// 5. XMLパーサを解放します。
71// xml_parser_free() はXMLパーサによって使用されたメモリを解放します。
72xml_parser_free($parser);
73
74?>

PHPのxml_set_notation_decl_handler関数は、XML文書のDTD（Document Type Definition）内で定義されるNOTATION宣言を検出したときに、特定の処理を行うための関数（ハンドラ）を設定する際に使用されます。NOTATION宣言は、XML文書が参照する画像ファイル形式などの、XML以外の外部データの種類をパーサに伝えるための仕組みです。

引数には、xml_parser_create()で作成したXMLパーサのインスタンスと、NOTATION宣言が検出された際に実行したいコールバック関数を指定します。この関数を登録すると、設定が成功したことを示すtrueが返されます。

サンプルコードでは、まずXMLパーサを作成し、notationDeclHandlerという関数をNOTATION宣言用のハンドラとして登録しています。その後、NOTATION宣言を含むXMLデータをパースすると、XMLパーサは定義された各NOTATIONを検出するたびに、登録されたnotationDeclHandlerを自動的に呼び出します。notationDeclHandler関数には、検出されたNOTATIONの名前や識別子などの詳細情報が渡されるため、それらを利用して外部データの種類に応じた処理を実装できます。これにより、XML文書が外部データに依存する場合でも、その情報を適切に扱う準備が整います。処理の完了後には、パーサのリソースを解放しています。

Copy
1<?php
2
3/**
4 * カスタムエラーハンドラ関数
5 * PHPが通常出力する警告やエラーメッセージを捕捉し、独自に処理します。
6 *
7 * @param int    $errno   エラーレベル（例: E_WARNING, E_NOTICE）
8 * @param string $errstr  エラーメッセージ
9 * @param string $errfile エラーが発生したファイル名
10 * @param int    $errline エラーが発生した行番号
11 * @return bool trueを返すと、PHPの通常のエラーハンドリング（エラーメッセージの表示など）を抑制します。
12 */
13function myErrorHandler(int $errno, string $errstr, string $errfile, int $errline): bool
14{
15    echo "--- カスタムエラーハンドラが捕捉しました ---\n";
16    echo "  エラーレベル: " . $errno . "\n";
17    echo "  メッセージ: " . $errstr . "\n";
18    echo "  ファイル: " . $errfile . "\n";
19    echo "  行: " . $errline . "\n";
20    echo "-------------------------------------------\n";
21    return true; // デフォルトのPHPエラーハンドラを抑制
22}
23
24/**
25 * XMLのNOTATION宣言を処理するハンドラ関数。
26 * xml_set_notation_decl_handlerに設定され、XMLドキュメント内でNOTATION宣言が見つかると呼び出されます。
27 *
28 * @param XMLParser $parser      XMLパーサオブジェクト
29 * @param string    $notationName NOTATIONの名前
30 * @param string|null $base      ベースURI (システム識別子が相対パスの場合に適用)
31 * @param string|null $systemId  システム識別子 (外部エンティティのURIなど)
32 * @param string|null $publicId  公開識別子 (よく知られたDTDの公開識別子など)
33 */
34function myNotationDeclHandler(XMLParser $parser, string $notationName, ?string $base, ?string $systemId, ?string $publicId): void
35{
36    echo "--- NOTATION宣言が見つかりました ---\n";
37    echo "  名前: " . $notationName . "\n";
38    echo "  ベース: " . ($base ?? 'N/A') . "\n"; // nullの場合 'N/A' を表示
39    echo "  システムID: " . ($systemId ?? 'N/A') . "\n";
40    echo "  公開ID: " . ($publicId ?? 'N/A') . "\n";
41    echo "-------------------------------------\n";
42}
43
44/**
45 * XMLパースとエラーハンドリングのデモンストレーションを行う関数。
46 * xml_set_notation_decl_handlerとset_error_handlerの使い方を示します。
47 */
48function demonstrateXmlParsingAndErrorHandling(): void
49{
50    // PHPの実行時エラー（警告など）を捕捉するためにカスタムエラーハンドラを設定
51    // これにより、通常のPHPエラーがmyErrorHandler関数で処理されるようになります。
52    set_error_handler('myErrorHandler');
53
54    // NOTATION宣言を含むXMLデータ
55    // NOTATION宣言は、XMLで外部の非XMLデータを参照する際に使われます（例: 画像形式など）。
56    $xmlData = <<<XML
57<?xml version="1.0" encoding="UTF-8"?>
58<!DOCTYPE document [
59  <!-- NOTATION宣言の例 -->
60  <!NOTATION gif SYSTEM "image/gif">
61  <!NOTATION jpeg PUBLIC "-//W3C//DTD JPEG//EN" "image/jpeg">
62  <!ELEMENT document (file*)>
63  <!ATTLIST file
64    name CDATA #REQUIRED
65    type NOTATION (gif | jpeg) #REQUIRED
66  >
67]>
68<document>
69  <file name="report.gif" type="gif"/>
70  <file name="photo.jpg" type="jpeg"/>
71</document>
72XML;
73
74    // XMLパーサを作成します。
75    // ここで、意図的に無効なエンコーディングを指定してPHPの警告 (E_WARNING) を発生させます。
76    // この警告は set_error_handler で設定した myErrorHandler によって捕捉されます。
77    // 実際には、'UTF-8' などの有効なエンコーディングを指定すべきです。
78    $parser = xml_parser_create('INVALID-ENCODING');
79
80    // xml_parser_createが失敗した場合 (nullまたはfalseを返す場合) のチェック
81    if ($parser === false) {
82        echo "致命的なエラー: XMLパーサの作成に失敗しました。\n";
83        restore_error_handler(); // エラーハンドラを元に戻す
84        return;
85    }
86
87    // NOTATION宣言ハンドラを設定します。
88    // XMLドキュメント内のNOTATION宣言が見つかると、myNotationDeclHandler関数が呼び出されます。
89    if (!xml_set_notation_decl_handler($parser, 'myNotationDeclHandler')) {
90        echo "エラー: NOTATION宣言ハンドラの設定に失敗しました。\n";
91        xml_parser_free($parser); // パーサを解放
92        restore_error_handler();
93        return;
94    }
95
96    // XMLデータをパースします。
97    // xml_parseは、パースエラーが発生した場合に false を返します。
98    // このパースエラーはPHPの警告ではないため、myErrorHandlerでは捕捉されません。
99    // その代わり、xml_get_error_codeなどで詳細なエラー情報を取得できます。
100    if (!xml_parse($parser, $xmlData, true)) {
101        $errorCode = xml_get_error_code($parser);
102        $errorString = xml_error_string($errorCode);
103        $currentLine = xml_get_current_line_number($parser);
104        echo "--- XMLパースエラーが発生しました ---\n";
105        echo "  コード: " . $errorCode . "\n";
106        echo "  メッセージ: " . $errorString . "\n";
107        echo "  行: " . $currentLine . "\n";
108        echo "-------------------------------------\n";
109    }
110
111    // XMLパーサが使用したリソースを解放します。
112    xml_parser_free($parser);
113
114    // カスタムエラーハンドラを解除し、PHPのデフォルトのエラーハンドリングに戻します。
115    restore_error_handler();
116}
117
118// デモンストレーション関数の実行
119demonstrateXmlParsingAndErrorHandling();

PHP 8のxml_set_notation_decl_handler関数は、XMLドキュメント内で定義されるNOTATION宣言を処理するためのカスタムハンドラを設定するものです。NOTATION宣言は、XMLが外部の非XMLデータを参照する際などに利用される、データ形式に関する情報を提供する機能です。

この関数は、最初の引数XMLParser $parserで、どのXMLパーサにハンドラを設定するかを指定します。二番目の引数callable|string|null $handlerには、XMLドキュメント内でNOTATION宣言が見つかったときに実行されるコールバック関数を指定します。この引数には関数名（文字列）またはクロージャなどの呼び出し可能なオブジェクトを渡すことができます。nullを指定すると、既存のハンドラを解除します。関数はハンドラの設定が成功した場合にtrueを返します。

サンプルコードでは、myNotationDeclHandler関数がNOTATION宣言ハンドラとして設定されており、XMLデータに含まれる<!NOTATION ...>といった記述を検出すると、この関数が自動的に呼び出され、宣言されたNOTATIONの詳細が表示されます。

また、このサンプルコードは、PHPのset_error_handler関数の使い方を示す例も兼ねています。set_error_handlerを用いてカスタムエラーハンドラmyErrorHandlerを設定することで、XMLパーサの作成時など、XML処理中に発生するPHPの警告（E_WARNING）などの実行時エラーを、PHPのデフォルトの表示ではなく、独自のロジックで捕捉し処理できるようになります。これにより、XMLパースにおける様々なエラー状況を柔軟に制御し、アプリケーションの堅牢性を高めることが可能になります。