【PHP8.x】entitiesプロパティの使い方

Copy
1<?php
2
3/**
4 * XMLドキュメントからDTDエンティティの定義を取得し、その情報を表示します。
5 *
6 * この関数は、XMLのDTD（Document Type Definition）で定義されたカスタムエンティティが、
7 * ドキュメント内でどのように「符号化」または「表現」されるか（エンティティ名とその実体値）を示します。
8 * 「php entities encode」というキーワードに関連して、エンティティの定義内容が
9 * 実際にXML内で何に「エンコード」（置き換え）されるかを示しています。
10 * システムエンジニアを目指す初心者の方でも、DTDエンティティの概念と、
11 * それをPHPでプログラムからどう扱うかを理解しやすいように設計されています。
12 *
13 * @param string $xmlString DTDを含むXML文字列。
14 * @return void
15 */
16function displayXmlEntities(string $xmlString): void
17{
18    // DOMDocumentオブジェクトを作成します。
19    // これはXMLパーサーとして機能し、XMLドキュメントの構造を操作するための基盤となります。
20    $dom = new Dom\DOMDocument();
21    // 厳密なエラーチェックを有効にし、XMLの構文解析時に問題があれば通知するようにします。
22    $dom->validateOnParse = true;
23
24    // 提供されたXML文字列をDOMDocumentにロードします。
25    // loadXML()メソッドは、文字列からXMLドキュメントを解析します。
26    // このプロセスで、XML内に定義されたDTDエンティティも読み込まれます。
27    $dom->loadXML($xmlString);
28
29    // ドキュメントタイプノードを取得します。
30    // XMLドキュメントのDTD情報（エンティティ定義など）がこのオブジェクトに含まれています。
31    $documentType = $dom->doctype;
32
33    // ドキュメントタイプノードが存在する場合のみ処理を進めます。
34    // DTDが定義されていないXMLやHTMLドキュメントでは、$documentType は null になります。
35    if ($documentType instanceof Dom\DocumentType) {
36        echo "--- DTDエンティティのリスト ---\n";
37
38        // Dom\DocumentType::entities プロパティは、DTDで定義されたエンティティの
39        // DOMNamedNodeMap（名前でアクセス可能なノードのコレクション）を返します。
40        // ここには、各エンティティがどのような値に「エンコード」（置き換え）されるかの
41        // 定義がコレクションとして含まれています。
42        $entities = $documentType->entities;
43
44        // エンティティが1つ以上定義されているか確認します。
45        if ($entities->length > 0) {
46            // 各エンティティノードをループして情報を表示します。
47            foreach ($entities as $entity) {
48                /** @var Dom\DOMEntity $entity */ // 型ヒント：$entityがDom\DOMEntityであることを示します
49                echo "  エンティティ名: " . $entity->nodeName . "\n";
50                // nodeValue は、そのエンティティがXMLドキュメント内で参照された場合に、
51                // 実際に展開される文字列（「実体値」）を示します。
52                // これは、エンティティが何に「エンコード」されているかを示していると言えます。
53                echo "  実体値 (エンコードされた内容): " . $entity->nodeValue . "\n";
54                echo "\n";
55            }
56        } else {
57            echo "  このドキュメントタイプにはエンティティ定義が見つかりませんでした。\n";
58        }
59    } else {
60        echo "ドキュメントタイプノードが見つかりませんでした。\n";
61        echo "XMLにDTD（Document Type Definition）が定義されていない可能性があります。\n";
62    }
63}
64
65// --------------------------------------------------------------------------
66// サンプルコードの実行例
67// --------------------------------------------------------------------------
68
69// DTD内部サブセットでカスタムエンティティを定義したXML文字列の例。
70// <!DOCTYPE document [...]> の部分で 'greeting', 'company', 'copyright' という
71// 3つのエンティティが定義されています。
72$sampleXmlWithEntities = <<<XML
73<!DOCTYPE document [
74  <!ENTITY greeting "Hello, World!">
75  <!ENTITY company "Example Corp.">
76  <!ENTITY copyright "Copyright &#xA9; 2023.">
77]>
78<document>
79  <message>&greeting;</message>
80  <info>Manufactured by &company;.</info>
81  <footer>&copyright;</footer>
82</document>
83XML;
84
85// 上記のXML文字列を解析し、DTDエンティティの情報を表示します。
86displayXmlEntities($sampleXmlWithEntities);
87
88?>

このPHPサンプルコードは、XMLドキュメント内に定義されたDTD（Document Type Definition）エンティティの情報を取得し、表示する方法を示しています。エンティティとは、XML内で特定の名前を定義し、それを別の文字列（実体値）に「エンコード」（置き換え）する仕組みです。これにより、共通のテキストや特殊文字を簡潔に表現できます。

コードの中心となるのは、Dom\DocumentTypeクラスのentitiesプロパティです。このプロパティは、DTDで定義されたすべてのエンティティのコレクションをDOMNamedNodeMapとして返します。このコレクションに含まれる各エンティティは、エンティティ名（nodeName）と、それが実際にXML内で何に「エンコード」（置き換え）されるかを示す実体値（nodeValue）を持っています。

displayXmlEntities関数は、DTDを含むXML文字列を引数（$xmlString）として受け取ります。関数内部では、まずDom\DOMDocumentオブジェクトにXMLをロードし、$dom->doctypeプロパティでドキュメントタイプ情報を取得します。次に、$documentType->entitiesプロパティを用いてエンティティのコレクションを取得し、その中をループして各エンティティの名前と実体値を画面に出力します。この関数自体は情報を表示するのみで、特定の値を返しません（void）。Dom\DocumentType::entitiesプロパティは引数を取らず、DOMNamedNodeMapを戻り値として返します。これにより、プログラムからXMLのDTDエンティティ定義を正確に把握し、利用することが可能となります。