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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMNode::replaceChild を使用してXMLの要素を置き換えるサンプルコード。
7 *
8 * この関数は、指定されたXML文字列内の特定の要素を新しい要素で置き換えて、
9 * 結果を標準出力に表示します。
10 */
11function replaceXmlElementExample(): void
12{
13    // 1. DOMDocumentオブジェクトを生成し、XMLを読み込む準備をします。
14    $dom = new DOMDocument('1.0', 'UTF-8');
15
16    // 出力時に見やすいようにインデントを整形する設定
17    $dom->formatOutput = true;
18
19    // 2. 操作の元となるXML文字列を定義します。
20    $xmlString = <<<XML
21<?xml version="1.0" encoding="UTF-8"?>
22<bookstore>
23  <book category="cooking">
24    <title lang="en">Everyday Italian</title>
25    <author>Giada De Laurentiis</author>
26  </book>
27  <book category="web">
28    <title lang="en">Learning XML</title>
29    <author>Erik T. Ray</author>
30  </book>
31</bookstore>
32XML;
33
34    // XML文字列をDOMオブジェクトとして読み込みます。
35    $dom->loadXML($xmlString);
36
37    // 3. 置き換えたい古いノード（最初の<book>要素）を取得します。
38    // getElementsByTagNameはDOMNodeListを返すため、item(0)で最初の要素を取得します。
39    $oldChild = $dom->getElementsByTagName('book')->item(0);
40
41    // 4. 新しく挿入するノード（<novel>要素）を作成します。
42    $newChild = $dom->createElement('novel', 'これは新しい小説の要素です。');
43    $newChild->setAttribute('category', 'fiction'); // 属性も追加できます
44
45    // 5. 親ノード（<bookstore>）を取得し、replaceChildメソッドを実行します。
46    // 親ノード上で replaceChild($newChild, $oldChild) を呼び出すことで、
47    // $oldChildが$newChildに置き換えられます。
48    if ($oldChild && $oldChild->parentNode) {
49        // replaceChildは、成功した場合に置き換えられた古いノード($oldChild)を返します。
50        $replacedNode = $oldChild->parentNode->replaceChild($newChild, $oldChild);
51    }
52
53    // 6. 結果のXMLを文字列として出力します。
54    // 最初の<book>要素が<novel>要素に置き換わっていることが確認できます。
55    echo $dom->saveXML();
56}
57
58// サンプル関数を実行します。
59replaceXmlElementExample();

DOMNode::replaceChildは、あるノードが持つ子ノードを、別の新しいノードに置き換えるためのメソッドです。XMLやHTML文書の特定の部分をプログラムで動的に書き換える際に使用します。

このサンプルコードでは、まずDOMDocumentクラスを利用して文字列のXMLデータを読み込み、プログラムで操作できるオブジェクトを生成します。次に、getElementsByTagNameメソッドで置き換え対象となる最初の<book>要素を取得し、これを古いノード$oldChildとします。同時にcreateElementメソッドで、新しく挿入したい<novel>要素を$newChildとして作成します。

replaceChildメソッドは、置き換えたい要素の親ノード（この場合は<bookstore>）から呼び出します。第1引数に新しいノード$newChildを、第2引数に置き換えたい既存の子ノード$oldChildを指定します。このメソッドは、処理が成功すると置き換えられて削除された古いノード（$oldChild）を返します。失敗した場合はfalseが返ります。

最終的にsaveXMLメソッドで変更後のXMLを出力すると、最初の<book>要素が<novel>要素に置き換わっていることを確認できます。

Copy
1<?php
2
3/**
4 * Dom\EntityReference::replaceChild の使用例を示します。
5 *
6 * DOMの仕様上、エンティティ参照ノードの子ノードは読み取り専用であり、変更できません。
7 * そのため、このメソッドを呼び出すと常に DOMException がスローされます。
8 * このサンプルコードは、その動作を try-catch ブロックを用いて実証します。
9 */
10function demonstrateEntityReferenceReplaceChild(): void
11{
12    // DOMDocument オブジェクトを初期化します。
13    $dom = new DOMDocument();
14
15    // DTD (文書型定義) を含むXML文字列を定義します。
16    // ここでは 'example' という名前のエンティティを宣言しています。
17    $xmlString = <<<XML
18    <?xml version="1.0" encoding="utf-8"?>
19    <!DOCTYPE root [
20        <!ENTITY example "これはエンティティのテキストです">
21    ]>
22    <root>&example;</root>
23    XML;
24
25    // XML文字列を読み込みます。
26    // エンティティ参照(&example;)を DOMEntityReference ノードとして扱うため、
27    // オプションは指定しません。
28    $dom->loadXML($xmlString);
29
30    // <root>要素の子ノードであるエンティティ参照ノードを取得します。
31    /** @var DOMEntityReference $entityRef */
32    $entityRef = $dom->documentElement->firstChild;
33
34    // 置き換えるための新しい要素ノードを作成します。
35    $newChild = $dom->createElement('newNode', '新しいノード');
36    
37    // 置き換え対象の古いノードとして、ダミーのノードを作成します。
38    // エンティティ参照は子を持てないため、実際の oldChild を取得することはできません。
39    $dummyOldChild = $dom->createElement('dummy');
40
41    try {
42        // エンティティ参照ノードの子を置き換えようと試みます。
43        // ここで必ず DOMException (No Modification Allowed Error) がスローされます。
44        $entityRef->replaceChild($newChild, $dummyOldChild);
45        
46        // 例外がスローされるため、この行は実行されません。
47        echo "ノードの置き換えに成功しました。";
48
49    } catch (DOMException $e) {
50        // 捕捉した例外のメッセージを表示します。
51        echo "予期された例外が発生しました: " . $e->getMessage() . PHP_EOL;
52        echo "結論: Dom\\EntityReference の子ノードは仕様により変更不可能です。" . PHP_EOL;
53    }
54}
55
56// 関数を実行してデモを行います。
57demonstrateEntityReferenceReplaceChild();

Dom\EntityReference::replaceChildは、エンティティ参照ノードが持つ特定の子ノードを、新しいノードに置き換えるためのメソッドです。第一引数 $newChild には新しく挿入するノードを、第二引数 $oldChild には置き換えたい既存の子ノードを指定します。成功した場合は置き換えられたノードを返しますが、Dom\EntityReferenceに対して使用した場合は、このメソッドの挙動が異なります。

このサンプルコードが示している最も重要な点は、DOMの仕様上、エンティティ参照ノードの子ノードは「読み取り専用」であるというルールです。これにより、子ノードの追加、削除、置換といった一切の変更操作が許可されていません。そのため、Dom\EntityReferenceオブジェクトに対してreplaceChildメソッドを呼び出すと、必ずDOMExceptionという種類の例外（エラー）が発生し、処理が中断されます。

コードでは、この仕様を実証するためにtry-catch構文を使用しています。tryブロック内で意図的に例外を発生させ、catchブロックでそれを捕捉することで、プログラムを停止させることなく、エンティティ参照ノードが変更不可能であることを安全に確認し、その旨をメッセージとして表示しています。