Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【PHP8.x】DOMDocument::substituteEntitiesプロパティの使い方

substituteEntitiesプロパティの使い方について、初心者にもわかりやすく解説します。

作成日: 更新日:

基本的な使い方

substituteEntitiesプロパティは、XML文書を扱うPHPのDOMDocumentクラスにおいて、未定義のエンティティ参照をどのように処理するかを制御するブール値(真偽値)を保持するプロパティです。XML文書内では、<や&のような特殊文字を表すエンティティ参照がよく使われますが、これらのエンティティが文書のDTD(Document Type Definition)で定義されていない場合があります。

このプロパティの値をtrueに設定すると、DOMパーサーは文書内で見つかった未定義のエンティティ参照(例えば&my_custom_entity;)を、そのままの文字列として扱います。これにより、DTDがない、あるいはDTDに記載されていないエンティティが含まれるXML文書を解析する際に、エラーや警告が発生することなく処理を続行できます。この設定は、特に外部から提供されるXMLデータで、厳密なDTDの定義が保証されない場合に有用です。

一方、デフォルト値であるfalseに設定されている場合、DOMパーサーは未定義のエンティティ参照を見つけると警告を発し、その参照を適切に置換せずに処理を進める可能性があります。これは、XML文書が厳密な標準に準拠していることを前提とし、未定義のエンティティが予期せぬ問題を引き起こすのを避けたい場合に適しています。厳密なXMLの検証が必要な場合は、デフォルトのfalseのまま使用することが推奨されます。

構文(syntax)

1<?php
2$dom = new DOMDocument();
3$dom->substituteEntities = false;
4?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

bool

DOMDocument::substituteEntities プロパティは、エンティティ置換が有効かどうかを表す真偽値を返します。TRUE の場合、エンティティ置換が有効になり、FALSE の場合、無効になります。

サンプルコード

PHP DOMDocument::substituteEntities を制御する

1<?php
2
3/**
4 * DOMDocument::substituteEntities プロパティの動作を実演する関数。
5 *
6 * このプロパティは、XMLをパースする際にDTDで定義された実体参照を
7 * その値に置き換える(展開する)か、それとも実体参照ノードとして残すかを制御します。
8 * 標準の実体参照(例: &amp;, &lt;)は通常、常に展開されます。
9 *
10 * システムエンジニアを目指す初心者向けに、DOMツリーの内部構成の違いに焦点を当てて説明します。
11 */
12function demonstrateSubstituteEntities(): void
13{
14    // DTD (Document Type Definition) を含むXML文字列を定義します。
15    // DTD内で「&myentity;」というカスタム実体参照を「置換されたテキストです。」と定義しています。
16    $xmlWithDtd = <<<XML
17<?xml version="1.0" encoding="UTF-8"?>
18<!DOCTYPE root [
19  <!ENTITY myentity "置換されたテキストです。">
20]>
21<root>
22  <data>これはアンパサンド: &amp; 、カスタム実体参照: &myentity;</data>
23</root>
24XML;
25
26    echo "--- substituteEntities = true の場合 ---\n";
27    // 新しい DOMDocument インスタンスを作成します。
28    $domTrue = new DOMDocument();
29    // preserveWhiteSpace と formatOutput を設定すると、XMLを整形して表示できます。(視認性向上のため)
30    $domTrue->preserveWhiteSpace = false;
31    $domTrue->formatOutput = true;
32
33    // substituteEntities を true に設定します。
34    // これにより、DTDで定義された実体参照(&myentity;)がパース時にその値に展開されます。
35    $domTrue->substituteEntities = true;
36    $domTrue->loadXML($xmlWithDtd);
37
38    echo "【XML全体】\n";
39    echo $domTrue->saveXML(); // 整形されたXMLを表示
40
41    echo "\n【dataノードの子ノード】\n";
42    // <data>ノードを取得し、その子ノードを走査してノードの型と値を確認します。
43    $dataNodeTrue = $domTrue->getElementsByTagName('data')->item(0);
44    foreach ($dataNodeTrue->childNodes as $node) {
45        // nodeType: 1(ELEMENT_NODE), 3(TEXT_NODE), 5(ENTITY_REF_NODE) など
46        echo sprintf(
47            "  - ノード名: %s, ノード型: %d (%s), 値: '%s'\n",
48            $node->nodeName,
49            $node->nodeType,
50            // DOMNode::nodeType の値に対応する定数名を表示(理解しやすくするため)
51            match ($node->nodeType) {
52                XML_ELEMENT_NODE => '要素ノード',
53                XML_ATTRIBUTE_NODE => '属性ノード',
54                XML_TEXT_NODE => 'テキストノード',
55                XML_CDATA_SECTION_NODE => 'CDATAセクションノード',
56                XML_ENTITY_REF_NODE => '実体参照ノード',
57                XML_ENTITY_NODE => '実体ノード',
58                XML_PI_NODE => '処理命令ノード',
59                XML_COMMENT_NODE => 'コメントノード',
60                XML_DOCUMENT_NODE => '文書ノード',
61                XML_DOCUMENT_TYPE_NODE => '文書型ノード',
62                XML_DOCUMENT_FRAG_NODE => '文書フラグメントノード',
63                XML_NOTATION_NODE => '記法ノード',
64                default => '不明',
65            },
66            $node->nodeValue
67        );
68    }
69    echo "→ 'true' の場合、カスタム実体参照 '&myentity;' はテキストノードとして展開されています。\n\n";
70
71    echo "--- substituteEntities = false の場合 ---\n";
72    // 新しい DOMDocument インスタンスを作成し、設定をリセットします。
73    $domFalse = new DOMDocument();
74    $domFalse->preserveWhiteSpace = false;
75    $domFalse->formatOutput = true;
76
77    // substituteEntities を false に設定します。
78    // これにより、DTDで定義された実体参照(&myentity;)はパース時に展開されず、
79    // DOMツリー内に「実体参照ノード(DOMEntityReference)」として残されます。
80    $domFalse->substituteEntities = false;
81    $domFalse->loadXML($xmlWithDtd);
82
83    echo "【XML全体】\n";
84    echo $domFalse->saveXML(); // 整形されたXMLを表示
85
86    echo "\n【dataノードの子ノード】\n";
87    $dataNodeFalse = $domFalse->getElementsByTagName('data')->item(0);
88    foreach ($dataNodeFalse->childNodes as $node) {
89        echo sprintf(
90            "  - ノード名: %s, ノード型: %d (%s), 値: '%s'\n",
91            $node->nodeName,
92            $node->nodeType,
93            match ($node->nodeType) {
94                XML_ELEMENT_NODE => '要素ノード',
95                XML_ATTRIBUTE_NODE => '属性ノード',
96                XML_TEXT_NODE => 'テキストノード',
97                XML_CDATA_SECTION_NODE => 'CDATAセクションノード',
98                XML_ENTITY_REF_NODE => '実体参照ノード',
99                XML_ENTITY_NODE => '実体ノード',
100                XML_PI_NODE => '処理命令ノード',
101                XML_COMMENT_NODE => 'コメントノード',
102                XML_DOCUMENT_NODE => '文書ノード',
103                XML_DOCUMENT_TYPE_NODE => '文書型ノード',
104                XML_DOCUMENT_FRAG_NODE => '文書フラグメントノード',
105                XML_NOTATION_NODE => '記法ノード',
106                default => '不明',
107            },
108            $node->nodeValue
109        );
110    }
111    echo "→ 'false' の場合、カスタム実体参照 '&myentity;' はDOMツリー内に\n";
112    echo "   '実体参照ノード (DOMEntityReference)' として残されていることがわかります。\n";
113    echo "   (このノード自体の nodeValue は空の場合が多いですが、nodeNameで判別できます。)\n";
114}
115
116// 関数を実行して、結果を出力します。
117demonstrateSubstituteEntities();

PHPのDOMDocument::substituteEntitiesプロパティは、XMLドキュメントをパースする際に、DTD(Document Type Definition)で定義された実体参照をどのように扱うかを制御するブール値のプロパティです。このプロパティは現在の設定値(trueまたはfalse)を返します。

このプロパティがtrueに設定されている場合、&myentity;のようなカスタム実体参照は、XMLがDOMDocumentに読み込まれる際に、その定義された値(例えば「置換されたテキストです。」)に展開されます。結果として、DOMツリー上ではそれらは通常のテキストノードとして表現されます。サンプルコードの最初の例では、&myentity;が「置換されたテキストです。」というテキストノードとして表示されているのがこの挙動です。

対照的に、このプロパティがfalseに設定されている場合、カスタム実体参照は展開されません。その代わりに、DOMツリー内にはDOMEntityReferenceという専用のノードとして保持されます。サンプルコードの二番目の例では、&myentity;がmyentityという名前の実体参照ノードとして存在していることが確認できます。これは、XMLの元々の構造や意図を保持したい場合に有効です。なお、&amp;や&lt;といったXML標準の実体参照は、このプロパティの設定にかかわらず通常は常に展開されます。このプロパティは、XMLデータの内部表現を細かく制御したいシステムで活用されます。

substituteEntitiesプロパティは、XMLを読み込む(loadXMLなど)前に設定する必要があります。設定後に読み込みを行うことで、期待通りの挙動になります。また、このプロパティはDTDで定義されたカスタム実体参照の展開を制御するものであり、&amp;や&lt;のような標準の実体参照は通常、この設定にかかわらず常に展開されますのでご注意ください。falseに設定した場合、DOMツリー上にはDOMEntityReferenceという特殊なノードが作成されます。このノードのnodeValueは空である場合が多いため、実体参照の名前を知るにはnodeNameプロパティを確認すると良いでしょう。XMLのDOMツリー構造をどう扱うかによって、このプロパティを適切に使い分けることが重要です。

PHP DOMDocument::substituteEntities を理解する

1<?php
2
3/**
4 * DOMDocument::substituteEntities プロパティの動作を実演する関数です。
5 *
6 * このプロパティは、XML ドキュメントをパースする際に、
7 * DTD (Document Type Definition) で定義されたエンティティ参照を
8 * その実体 (具体的な値) に置換するかどうかを制御します。
9 *
10 * デフォルトでは true (置換する) に設定されています。
11 * false に設定すると、エンティティ参照は置換されずに、
12 * DOMツリー上で独立した「エンティティ参照ノード」として扱われます。
13 */
14function demonstrateSubstituteEntitiesProperty(): void
15{
16    // DTD内で「greeting」というカスタムエンティティを定義したXML文字列
17    $xmlStringWithEntity = <<<XML
18<?xml version="1.0"?>
19<!DOCTYPE root [
20  <!ENTITY greeting "Hello PHP World!">
21]>
22<root>Message: &greeting; from PHP.</root>
23XML;
24
25    echo "--- DOMDocument::substituteEntities が false の場合 ---\n";
26    // 新しい DOMDocument オブジェクトを作成
27    $domFalse = new DOMDocument();
28    // substituteEntities プロパティを false に設定。これにより、エンティティは置換されません。
29    $domFalse->substituteEntities = false;
30
31    // XML文字列をロード
32    if (!$domFalse->loadXML($xmlStringWithEntity)) {
33        echo "XMLのロードに失敗しました (substituteEntities = false)。\n";
34    } else {
35        echo "XMLをロードしました。ルート要素の子ノードを見てみましょう:\n";
36        $root = $domFalse->documentElement; // ルート要素 (<root>) を取得
37        if ($root) {
38            // ルート要素の子ノードをループして、ノードの種類と値を確認します
39            foreach ($root->childNodes as $node) {
40                // #text はテキストノード、エンティティ名は DOMEntityReference ノードを示します
41                echo "  ノードタイプ: " . ($node->nodeName === '#text' ? 'テキスト' : 'エンティティ参照') .
42                     " (名前: " . $node->nodeName . ", 値: '" . $node->nodeValue . "')\n";
43            }
44            echo "この場合、'&greeting;' はテキストとして置換されず、独立したエンティティ参照ノードとして扱われることがわかります。\n";
45        }
46    }
47
48    echo "\n--- DOMDocument::substituteEntities が true の場合 (デフォルト) ---\n";
49    // 新しい DOMDocument オブジェクトを作成
50    $domTrue = new DOMDocument();
51    // substituteEntities プロパティを true に設定します (これがデフォルト動作です)。
52    // 明示的に設定しなくても、この挙動になります。
53    $domTrue->substituteEntities = true;
54
55    // XML文字列をロード
56    if (!$domTrue->loadXML($xmlStringWithEntity)) {
57        echo "XMLのロードに失敗しました (substituteEntities = true)。\n";
58    } else {
59        echo "XMLをロードしました。ルート要素の子ノードを見てみましょう:\n";
60        $root = $domTrue->documentElement; // ルート要素 (<root>) を取得
61        if ($root) {
62            // ルート要素の子ノードをループして、ノードの種類と値を確認します
63            foreach ($root->childNodes as $node) {
64                echo "  ノードタイプ: " . ($node->nodeName === '#text' ? 'テキスト' : 'エンティティ参照') .
65                     " (名前: " . $node->nodeName . ", 値: '" . $node->nodeValue . "')\n";
66            }
67            echo "この場合、'&greeting;' は定義された実体 ('Hello PHP World!') に置換され、\n";
68            echo "テキストノードの一部として処理されていることがわかります。\n";
69        }
70    }
71}
72
73// 関数を実行して、DOMDocument::substituteEntities プロパティの動作を確認します。
74demonstrateSubstituteEntitiesProperty();

DOMDocument::substituteEntitiesは、XMLドキュメントを読み込む際に、DTD(Document Type Definition)で定義されたエンティティ参照を、その実体(実際の値)に置換するかどうかを制御するプロパティです。このプロパティは引数を取らず、bool型の値を設定し、XMLパースの挙動に影響を与えます。デフォルトではtrueに設定されており、エンティティ参照は対応する実体値に置換され、DOMツリー上では通常のテキストノードの一部として扱われます。

一方、substituteEntitiesをfalseに設定すると、エンティティ参照は実体に置換されず、DOMツリー上では独立したDOMEntityReferenceノードとして扱われます。これにより、XMLの構造をそのまま保持したい場合や、エンティティ参照自体を操作したい場合に有用です。

サンプルコードでは、&greeting;というカスタムエンティティを含むXMLを例に、このプロパティの動作を比較しています。substituteEntitiesがfalseの場合、パース後にgreetingというエンティティ参照ノードとして認識されることが示されます。対照的に、substituteEntitiesがtrue(デフォルト)の場合、&greeting;は定義された実体値「Hello PHP World!」に置換され、通常のテキストノードとしてDOMツリーに組み込まれる様子が確認できます。このプロパティは、XMLドキュメントをどのようにDOMツリーとして表現するかを制御するために使用されます。

このDOMDocument::substituteEntitiesプロパティは、XMLドキュメント内のDTDで定義されたエンティティ参照を、その具体的な値に置換するかどうかを制御します。デフォルトのtrueでは、エンティティは置換されて通常のテキストノードの一部となるため、XMLの内容を直接的に取得しやすいです。一方、falseに設定すると、エンティティ参照は置換されず、独立したDOMEntityReferenceノードとしてDOMツリー上に残ります。このため、初心者の方は、どちらの設定でエンティティ参照が「#text」として展開されるか、「エンティティ参照ノード」として残るかを理解していないと、期待するテキストが取得できない原因になります。このプロパティはXMLをロードする前に設定する必要があり、後から変更しても効果はありません。また、外部DTDを使用する際は、セキュリティ上のリスク(XXE攻撃など)を防ぐため、信頼できないソースからのXML処理には十分注意し、適切なセキュリティ対策と併用してください。

関連コンテンツ

関連IT用語

関連プログラミング言語