【PHP8.x】DOMEntityReference::replaceChild()メソッドの使い方

Copy
1<?php
2
3/**
4 * DOMEntityReference::replaceChild の使用例を示します。
5 *
6 * この関数は、DTDで定義されたエンティティ参照を持つXMLドキュメントを読み込み、
7 * そのエンティティ参照ノードが持つ子ノード（テキストノード）を
8 * 別の新しいテキストノードに置き換える処理を実演します。
9 */
10function demonstrateDomEntityReferenceReplaceChild(): void
11{
12    // 1. DTDでエンティティ "&author;" を定義したXML文字列を準備します。
13    $xmlString = <<<XML
14    <?xml version="1.0" encoding="UTF-8"?>
15    <!DOCTYPE message [
16        <!ENTITY author "Taro Yamada">
17    ]>
18    <message>
19        <from>&author;</from>
20        <to>Jiro Suzuki</to>
21    </message>
22    XML;
23
24    // 2. DOMDocumentオブジェクトを生成し、XMLをロードします。
25    $dom = new DOMDocument();
26    // 出力を整形するための設定
27    $dom->preserveWhiteSpace = false;
28    $dom->formatOutput = true;
29    $dom->loadXML($xmlString);
30
31    // 3. DOMEntityReferenceノード (&author;) を取得します。
32    // <from>要素を取得
33    $fromElement = $dom->getElementsByTagName('from')->item(0);
34    // <from>要素の最初の子ノードがエンティティ参照ノードです。
35    $entityRefNode = $fromElement->firstChild;
36
37    // 4. 取得したノードがDOMEntityReferenceのインスタンスか確認します。
38    if ($entityRefNode instanceof DOMEntityReference) {
39        // 5. 置き換え対象となる古い子ノードと、新しい子ノードを準備します。
40        
41        // 古い子ノードは、エンティティが展開された結果のテキストノード "Taro Yamada" です。
42        $oldChild = $entityRefNode->firstChild;
43        
44        // 新しい子ノードとして、"Hanako Tanaka" というテキストノードを生成します。
45        $newChild = $dom->createTextNode('Hanako Tanaka');
46
47        // 6. DOMEntityReference::replaceChild() を呼び出し、子ノードを置き換えます。
48        // 第1引数に新しいノード、第2引数に古いノードを指定します。
49        $entityRefNode->replaceChild($newChild, $oldChild);
50        
51        // 7. 変更後のXMLを出力して結果を確認します。
52        // <from>要素内のエンティティの内容が置き換えられていることが確認できます。
53        echo $dom->saveXML();
54    } else {
55        echo "DOMEntityReferenceノードが見つかりませんでした。\n";
56    }
57}
58
59// 関数を実行します。
60demonstrateDomEntityReferenceReplaceChild();

DOMEntityReference::replaceChild()は、XMLドキュメント内のエンティティ参照ノードが持つ特定の子ノードを、新しいノードに置き換えるためのメソッドです。

このサンプルコードでは、まずDTD（文書型定義）で &author; というエンティティを「Taro Yamada」という値で定義したXML文字列を準備します。次に、DOMDocumentクラスを使ってこのXMLを読み込み、<from>要素内にある &author; というエンティティ参照ノードを取得します。

replaceChild()メソッドを呼び出すことで、このエンティティ参照ノードが持つ子ノードを置き換えます。メソッドは2つの引数を取ります。第1引数 $newChild には、新しく挿入したいノード（この例では「Hanako Tanaka」というテキストノード）を指定します。第2引数 $oldChild には、置き換え対象となる既存の子ノード（エンティティが展開された結果である「Taro Yamada」のテキストノード）を指定します。

メソッドの実行に成功すると、戻り値として置き換えられた古いノードが返されます。失敗した場合は false が返ります。最終的に変更後のXMLを出力すると、<from>要素の内容が「Hanako Tanaka」に書き換わっていることが確認できます。このように、エンティティ参照が持つ具体的な内容をプログラムで動的に変更することが可能です。

Copy
1<?php
2
3/**
4 * DOMEntityReference::replaceChild の動作を示すサンプルコードです。
5 *
6 * DOMEntityReference ノードは仕様上読み取り専用であり、その子ノードも変更できません。
7 * そのため、このメソッドを呼び出すと DOMException がスローされます。
8 * このサンプルでは、その挙動を try-catch ブロックを用いて確認します。
9 */
10function domEntityReferenceReplaceChildExample(): void
11{
12    // エンティティ 'example_entity' を定義し、<data>要素内で参照するXML文字列
13    $xmlString = <<<XML
14    <?xml version="1.0" encoding="UTF-8"?>
15    <!DOCTYPE root [
16        <!ENTITY example_entity "This is an original entity text.">
17    ]>
18    <root>
19        <data>&example_entity;</data>
20    </root>
21    XML;
22
23    // DOMDocument オブジェクトを生成
24    $dom = new DOMDocument();
25
26    // XMLを解析する際にエンティティ参照を自動で展開しないように設定します。
27    // これにより、DOMツリー内に DOMEntityReference ノード (&example_entity;) が作成されます。
28    $dom->substituteEntities = false;
29    $dom->loadXML($xmlString);
30
31    // <data>要素を取得
32    $dataElement = $dom->getElementsByTagName('data')->item(0);
33
34    // <data>要素の子であるエンティティ参照ノード (&example_entity;) を取得
35    // このノードの型は DOMEntityReference です。
36    $entityRefNode = $dataElement->firstChild;
37
38    try {
39        // 置き換え対象となる古い子ノード (エンティティが展開されたテキストノード)
40        $oldChild = $entityRefNode->firstChild;
41
42        // 新しい子ノードとしてテキストノードを作成
43        $newChild = $dom->createTextNode("This is a new text.");
44
45        // エンティティ参照ノードの子ノードを置き換えようと試みます。
46        // ここで DOMException (NO_MODIFICATION_ALLOWED_ERR) がスローされます。
47        $replacedNode = $entityRefNode->replaceChild($newChild, $oldChild);
48
49        // 例外が発生しなかった場合 (通常はここには到達しません)
50        echo "Node was replaced successfully." . PHP_EOL;
51
52    } catch (DOMException $e) {
53        // 期待される例外を捕捉し、メッセージを表示します。
54        echo "期待どおりの例外が発生しました: " . $e->getMessage() . PHP_EOL;
55        echo "これは DOMEntityReference ノードが読み取り専用であることを示しています。" . PHP_EOL;
56    }
57}
58
59// 関数を実行
60domEntityReferenceReplaceChildExample();

DOMEntityReference::replaceChild()は、エンティティ参照ノードが持つ子ノードを、別の新しいノードに置き換えるためのメソッドです。しかし、DOMの仕様上、DOMEntityReferenceノードとその子孫は読み取り専用であり、変更することができません。このサンプルコードは、実際にこのメソッドを呼び出すとエラーが発生することを確認し、その仕様を理解することを目的としています。

コードでは、まずエンティティ参照 &example_entity; を含むXMLを読み込み、DOMツリー上に DOMEntityReference ノードを意図的に作成します。その後 try ブロック内で、このエンティティ参照ノードの子ノードを replaceChild() を使って置き換えようと試みています。

このメソッドの第1引数 $newChild には新しく挿入するノードを、第2引数 $oldChild には置き換え対象となる既存の子ノードを指定します。DOMEntityReference ノードは変更不可能なため、この操作は DOMException という例外を発生させます。コードは catch ブロックでこの例外を捕捉し、ノードが読み取り専用であることを示すメッセージを表示します。これにより、メソッドが意図通りに例外をスローする挙動を確認できます。