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

Copy
1<?php
2
3/**
4 * 従来のDOMDocumentノードをDom\XMLDocumentにインポートするサンプルコード。
5 *
6 * この関数は、PHP 8で導入されたDom\XMLDocumentクラスの
7 * `importLegacyNode` メソッドの利用方法を示します。
8 *
9 * リファレンス情報によると、`importLegacyNode` メソッドは
10 * 戻り値がない（void）とされていますが、一般的な `importNode` の
11 * 挙動としては、インポートされたノードを返し、それを新しいドキュメントツリーに
12 * 追加するのが一般的です。
13 *
14 * 以下のコードでは、一般的な `importNode` のパターンに従い、
15 * `importLegacyNode` がインポートされたノードを返すものと仮定して実装しています。
16 * （注: この仮定は提供されたリファレンス情報の「戻り値なし」と矛盾します。
17 * 実際のPHPの動作は異なる可能性があります。）
18 */
19function demonstrateXmlImportLegacyNode(): void
20{
21    // 1. 従来のDOMDocumentを作成し、インポート元のノードを準備します。
22    $legacyDoc = new DOMDocument('1.0', 'UTF-8');
23    $legacyRoot = $legacyDoc->createElement('legacyRoot');
24    $legacyDoc->appendChild($legacyRoot);
25
26    $legacyChild = $legacyDoc->createElement('legacyChild', 'Hello Legacy World!');
27    $legacyRoot->appendChild($legacyChild);
28
29    // 2. 新しいDom\XMLDocumentを作成します。
30    $newDoc = new Dom\XMLDocument('1.0', 'UTF-8');
31    $newRoot = $newDoc->createElement('newRoot');
32    $newDoc->appendChild($newRoot);
33
34    // 3. Dom\XMLDocument::importLegacyNode() を使用して、
35    //    従来のDOMNodeを新しいドキュメントのコンテキストにインポートします。
36    //    第2引数に true を指定することで、子ノードも再帰的にインポートされます。
37    //    (注: リファレンス情報では戻り値が void ですが、ここでは一般的なimportNodeの挙動に倣い、
38    //    インポートされたノードが返されると仮定して変数に格納します。)
39    /** @var \Dom\Node $importedNode */
40    $importedNode = $newDoc->importLegacyNode($legacyRoot, true);
41
42    // 4. インポートされたノードを、新しいDom\XMLDocumentのツリーに追加します。
43    $newRoot->appendChild($importedNode);
44
45    // 5. インポート後の新しいドキュメントの内容を出力します。
46    echo $newDoc->saveXML();
47}
48
49// サンプルコードを実行します。
50demonstrateXmlImportLegacyNode();

PHP 8で導入されたDom\XMLDocument::importLegacyNodeメソッドは、PHP 8よりも前のバージョンで利用されていたDOMDocumentクラスで作成されたXMLノードを、新しいDom\XMLDocumentのコンテキストに安全に移行させるために利用されます。これは、異なるDOM実装間でXML要素を統合する際に役立つ機能です。

このメソッドは二つの引数を取ります。最初の$nodeには、インポートしたい既存のDOMNodeオブジェクトを指定します。二番目の$deepは真偽値で、trueを設定すると、指定したノードとそのすべての子ノードが再帰的にインポートされます。falseの場合、指定したノードのみがインポートされ、子ノードはインポートされません。

リファレンス情報によると、importLegacyNodeメソッド自体は戻り値を持ちません（void）。これは、インポートされたノードが自動的に既存のドキュメントに追加されるのではなく、インポート後に別途、新しいドキュメントツリーの適切な位置に追加する必要があることを示唆しています。提供されたサンプルコードでは、一般的なDOMDocument::importNodeの挙動に倣い、インポートされたノードが返されると仮定して変数に格納していますが、実際のimportLegacyNodeは直接ノードを返さないため、この点には注意が必要です。サンプルコードでは、古いドキュメントからlegacyRootノードをdeepオプションをtrueにして新しいドキュメントにインポートし、その後newRootの子として追加する一連の流れを示しています。

Copy
1<?php
2
3// Dom\XMLDocument::importLegacyNode() の使用例
4// このメソッドは、PHPの古いDOM拡張 (DOMNode) で作成されたノードを、
5// PHP 8で導入された新しいDom\XMLDocumentインスタンスへインポートします。
6// 異なるDOM実装間でXMLノードを移行する際に役立ちます。
7
8// 1. 古いDOM拡張 (DOMDocument) でXMLを作成し、インポートしたいノードを用意します。
9$legacyDom = new DOMDocument('1.0', 'UTF-8');
10$legacyDom->loadXML('<old_root><element id="legacy-id">古い要素の内容</element><other_element/></old_root>');
11
12// インポートしたい古いDOMノード (例: 'element'タグ) を取得します。
13$nodeToImport = $legacyDom->getElementsByTagName('element')->item(0);
14
15if ($nodeToImport === null) {
16    echo "エラー: インポートするノードが見つかりませんでした。\n";
17    exit(1);
18}
19
20// 2. 新しいDom\XMLDocumentインスタンスを作成します。
21$newDom = new Dom\XMLDocument('1.0', 'UTF-8');
22
23// 新しいドキュメントにルート要素を追加します。
24$newRoot = $newDom->createElement('new_root');
25$newDom->appendChild($newRoot);
26
27// 3. Dom\XMLDocument::importLegacyNode() を使用してノードをインポートします。
28//    引数: $node (DOMNode) - インポートする古いノード
29//          $deep (bool) - trueの場合、ノードの子孫も全てインポートします (デフォルト: false)。
30$importedNode = $newDom->importLegacyNode($nodeToImport, true); // trueで子孫も再帰的にインポート
31
32// 4. インポートされたノードを新しいドキュメントのルート要素に追加します。
33$newRoot->appendChild($importedNode);
34
35// 5. 新しいDom\XMLDocumentの内容を出力して確認します。
36echo "新しいDom\\XMLDocumentの内容:\n";
37echo $newDom->saveXML();
38
39// 期待される出力例:
40// <?xml version="1.0" encoding="UTF-8"?>
41// <new_root>
42//   <element id="legacy-id">古い要素の内容</element>
43// </new_root>
44

PHP 8で導入されたDom\XMLDocumentクラスのimportLegacyNodeメソッドは、PHPの古いDOM拡張で作成されたDOMNodeオブジェクトを、新しいDom\XMLDocumentインスタンスへインポートするために使用します。これは、異なるDOM実装間でXMLノードを円滑に移行する際に非常に便利な機能です。

サンプルコードでは、まず古いDOMDocumentでXMLを作成し、インポートしたいelementノードを取得しています。次に、新しいDom\XMLDocumentインスタンスを作成し、ルート要素を追加します。そして、importLegacyNodeメソッドを使って、取得した古いノードを新しいドキュメントにインポートします。

このメソッドの第一引数$nodeには、インポートしたい既存のDOMNodeオブジェクトを指定します。第二引数$deepは真偽値で、trueを設定すると、インポートするノードだけでなく、その子孫ノードもすべて再帰的にインポートされます。falseの場合はノード自身のみがインポートされます。メソッドはインポートされた新しいDom\Nodeオブジェクトを返します。最後に、インポートされたノードを新しいドキュメントに追加し、内容を出力して確認しています。これにより、古いDOM構造の一部を新しいDOM環境へ簡単に統合できることがわかります。