いっしー@Webエンジニア
Webツールプログラミング言語プログラミング学習ITニュースIT用語辞典ポートフォリオ
Webエンジニア向けプログラミング解説動画をYouTubeで配信中！
▶ チャンネル登録はこちら

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

importLegacyNodeメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 更新日:

基本的な使い方

importLegacyNodeメソッドは、Dom\HTMLDocumentクラスに属し、従来のDOM拡張で作成されたノードを、現在のHTMLドキュメントにインポートするメソッドです。Dom\HTMLDocumentは、PHP 8で導入された新しいDOM拡張において、HTMLドキュメントの構造をプログラムから操作するための主要なクラスです。このメソッドの主な役割は、従来のDOMDocumentクラスなどで生成されたDOMNodeオブジェクトを、現在のDom\HTMLDocumentインスタンスが扱う新しいDom\Nodeオブジェクトとして変換し、ドキュメントに組み込むことです。これにより、異なるDOM実装間でのノードの移動や再利用が可能となり、特に古いPHPアプリケーションのDOM操作コードと、新しいDOM拡張を利用したコードとの間の互換性を確保する上で重要な役割を果たします。例えば、既存のシステムで作成されたHTML要素や属性を、新しいDOM拡張の環境下で利用したい場合に、このメソッドを用いることでスムーズな統合を実現できます。これは、システム移行や異なるライブラリ間での連携において、開発者が直面する互換性の課題を解決するための強力な機能です。

構文(syntax)

1<?php
2$htmlDocument = new DOM\HTMLDocument();
3$sourceDocument = new DOMDocument();
4$nodeToImport = $sourceDocument->createElement('div', 'Example Text');
5
6$importedNode = $htmlDocument->importLegacyNode($nodeToImport, true);

引数(parameters)

Dom\Node $node, bool $deep = false

  • Dom\Node $node: インポートするDOMノードを指定します。
  • bool $deep = false: trueを指定すると、指定したノードの子要素も再帰的にインポートします。デフォルトはfalseです。

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP importLegacyNodeで旧DOMノードをインポートする

1<?php
2
3/**
4 * 旧DOMエクステンションのノードをDom\HTMLDocumentにインポートする方法を示すサンプルコードです。
5 *
6 * Dom\HTMLDocument::importLegacyNode メソッドは、古い ext-dom 拡張の DOMNode オブジェクトを
7 * 新しい ext-dom 拡張の Dom\Node オブジェクトとしてインポートし、その新しいノードを返します。
8 * インポートされたノードは、まだドキュメントツリーには追加されていないため、
9 * appendChild などのメソッドを使って手動で追加する必要があります。
10 */
11function demonstrateImportLegacyNode(): void
12{
13    // 1. 旧DOMエクステンションでHTML要素を作成
14    // DOMDocument は、PHPの従来のDOM拡張（ext-dom）の一部です。
15    $oldDomDocument = new DOMDocument();
16    // HTML文字列をパースして、ボディや要素を含むドキュメントを作成します。
17    $oldDomDocument->loadHTML('
18        <html>
19            <body>
20                <p id="legacyParagraph">これは古いDOMからインポートされる段落です。</p>
21                <div id="legacyDiv"><span>インポートされるスパン要素</span></div>
22            </body>
23        </html>
24    ');
25
26    // 旧DOMDocumentからインポートしたいノードを取得します。
27    // getElementById は、IDに基づいて要素を効率的に取得するメソッドです。
28    $oldParagraphNode = $oldDomDocument->getElementById('legacyParagraph');
29    $oldDivNode = $oldDomDocument->getElementById('legacyDiv');
30    
31    if (!$oldParagraphNode || !$oldDivNode) {
32        echo "エラー: 旧DOMから必要なノードが見つかりませんでした。\n";
33        return;
34    }
35
36    echo "--- 元の旧DOMノードの情報 ---\n";
37    echo "元の段落ノード名: " . $oldParagraphNode->nodeName . ", テキスト内容: " . $oldParagraphNode->textContent . "\n";
38    echo "元のdivノード名: " . $oldDivNode->nodeName . ", 子ノード数: " . $oldDivNode->childNodes->length . "\n\n";
39
40    // 2. 新DomエクステンションのHTMLDocumentを作成
41    // Dom\HTMLDocument は、PHP 8で導入された新しいDom拡張の一部です。
42    $newHtmlDocument = new Dom\HTMLDocument();
43
44    // 3. 旧DOMノードを新Domドキュメントにインポートする
45    // importLegacyNode メソッドは、インポートされたノードのコピーを返します。
46    // このコピーは $newHtmlDocument のコンテキストに属します。
47
48    // 3.1. $deep = false の場合（子ノードはインポートされない）
49    echo "--- importLegacyNode (deep = false) のデモ ---\n";
50    // $oldParagraphNode は子ノードを持たないため、$deep の影響は小さいです。
51    $importedParagraph = $newHtmlDocument->importLegacyNode($oldParagraphNode, false);
52
53    // インポートされたノードはまだドキュメントツリーにないため、bodyに追加します。
54    $newHtmlDocument->body->appendChild($importedParagraph);
55
56    echo "新Domドキュメントの内容 (deep = false で段落をインポート):\n";
57    // saveHTML() は、ドキュメント全体のHTML文字列を生成します。
58    echo $newHtmlDocument->saveHTML() . "\n\n";
59    
60    // 3.2. $deep = true の場合（子ノードも再帰的にインポートされる）
61    // $deep の違いを明確にするため、新しい Dom\HTMLDocument インスタンスで試します。
62    $newHtmlDocumentDeep = new Dom\HTMLDocument();
63    echo "--- importLegacyNode (deep = true) のデモ ---\n";
64    
65    // $oldDivNode は子ノード（<span>）を持つため、$deep の違いが明確になります。
66    $importedDivDeep = $newHtmlDocumentDeep->importLegacyNode($oldDivNode, true);
67    
68    // インポートされたノードを新しいドキュメントのbodyに追加します。
69    $newHtmlDocumentDeep->body->appendChild($importedDivDeep);
70
71    echo "新Domドキュメントの内容 (deep = true でdivをインポート):\n";
72    echo $newHtmlDocumentDeep->saveHTML() . "\n\n";
73
74    // --- インポートされたノードのプロパティを確認 ---
75    echo "--- インポートされたノードの確認 ---\n";
76    echo "インポートされた段落ノードの親: " . ($importedParagraph->parentNode ? $importedParagraph->parentNode->nodeName : 'なし') . "\n";
77    echo "インポートされたdivノードの子ノード数 (deep = true): " . $importedDivDeep->childNodes->length . "\n";
78    if ($importedDivDeep->childNodes->length > 0) {
79        echo "インポートされたdivの最初の子ノード名 (deep = true): " . $importedDivDeep->childNodes->item(0)->nodeName . "\n";
80        echo "インポートされたdivの最初の子ノードのテキスト内容 (deep = true): " . $importedDivDeep->childNodes->item(0)->textContent . "\n";
81    }
82}
83
84// 関数を実行してデモンストレーションを開始します。
85demonstrateImportLegacyNode();

PHPのDom\HTMLDocument::importLegacyNodeメソッドは、従来のPHP DOM拡張（ext-dom）で作成されたDOMNodeオブジェクトを、PHP 8から利用可能な新しいDOM拡張のDom\HTMLDocumentにインポートするために利用されます。このメソッドは、引数として渡されたDom\Node $node（インポートしたい従来のDOMノード）のコピーを、新しいドキュメントのコンテキストに適合するDom\Nodeオブジェクトとして返します。

第二引数bool $deepは、子ノードも一緒にインポートするかどうかを制御します。trueを指定すると、元のノードとその全ての子ノードが再帰的にインポートされます。一方、デフォルト値のfalseでは、指定されたノード自身のみがインポートされ、子ノードは含まれません。インポートされたノードは、直ちにドキュメントツリーに追加されるわけではありませんので、ドキュメント内で実際に使用するには、appendChildなどのメソッドを用いて明示的に追加する必要があります。この機能は、古いDOM実装で生成されたHTMLコンテンツを、新しいDOM拡張ベースのシステムに安全かつ効率的に統合する際に役立ちます。

Dom\HTMLDocument::importLegacyNodeメソッドは、PHPの古いDOM拡張（DOMDocumentなど）で作成されたノードを、新しいDom拡張（Dom\HTMLDocument）のコンテキストに変換・コピーする際に使用します。インポートされた新しいDom\Nodeオブジェクトが戻り値として返されますが、これはドキュメントツリーには自動で追加されません。そのため、appendChildなどのメソッドを使って手動で新しいドキュメントに追加する必要があります。$deep引数をtrueにすると元のノードの子ノードも再帰的にコピーされますが、falseの場合は親ノードのみがコピーされるため、コンテンツ全体を移行したい場合はtrueを指定してください。元のノードは変更されず、新しいノードが生成される点にもご注意ください。

PHP importLegacyNode でノードをインポートする

1<?php
2
3/**
4 * 別のDOMドキュメントからノードを現在のHTMLドキュメントにインポートするサンプル。
5 *
6 * キーワード「php implementsとは」は、通常、クラスがインターフェースの契約を「実装する」ことを指します。
7 * Dom\HTMLDocument::importLegacyNode メソッドは、他のドキュメントで「実装された」（作成された）ノードを、
8 * 現在のHTMLドキュメントのコンテキストに「実装し直す」（適合させる）役割を担います。
9 * 提供されたリファレンス情報によると戻り値はありませんが、このメソッド呼び出しにより、
10 * 引数として渡されたノードが現在のドキュメントに属するよう変更されると仮定し、
11 * その後、ドキュメントツリーに手動で追加します。
12 */
13function demonstrateImportLegacyNode(): void
14{
15    // 1. メインドキュメントとして新しいHTMLドキュメントを準備します。
16    $mainDoc = new Dom\HTMLDocument();
17    $mainDoc->loadHTML('<!DOCTYPE html><html><head><title>Main Document</title></head><body><h1>Welcome to Main Doc</h1></body></html>');
18
19    // body要素を取得します。存在しない場合は作成します。
20    $mainBody = $mainDoc->getElementsByTagName('body')->item(0);
21    if (!$mainBody) {
22        $html = $mainDoc->getElementsByTagName('html')->item(0);
23        $mainBody = $mainDoc->createElement('body');
24        if ($html) {
25            $html->appendChild($mainBody);
26        } else {
27            echo "Error: Unable to initialize main document body.\n";
28            return;
29        }
30    }
31
32    echo "--- Main Document (Before Import) ---\n";
33    echo $mainDoc->saveHTML();
34    echo "\n";
35
36    // 2. インポート元のドキュメントとノードを準備します。
37    $sourceDoc = new Dom\HTMLDocument();
38    $sourceNode = $sourceDoc->createElement('div', 'Content from source document.');
39    // 子ノードも作成し、インポートされるノードに追加します。
40    $sourceNode->appendChild($sourceDoc->createElement('p', 'This is a child paragraph.'));
41
42    echo "--- Node to Import from Source Document ---\n";
43    echo $sourceDoc->saveHTML($sourceNode);
44    echo "\n";
45
46    // 3. Dom\HTMLDocument::importLegacyNode メソッドを呼び出し、ノードをメインドキュメントのコンテキストにインポートします。
47    // 第二引数 $deep は false なので、ノードの子孫ノードはインポートされません。
48    // リファレンス情報では戻り値がありません。このメソッドは $sourceNode の所有ドキュメントを $mainDoc に変更すると仮定します。
49    $mainDoc->importLegacyNode($sourceNode, false);
50
51    // 4. インポートされたノード（$sourceNode自身）をメインドキュメントのツリーに追加します。
52    // $sourceNode が $mainDoc に属するようになったため、appendChild で追加できます。
53    try {
54        $mainBody->appendChild($sourceNode);
55
56        echo "--- Main Document (After Import and Append) ---\n";
57        echo $mainDoc->saveHTML();
58        echo "\n";
59
60        echo "注意: importLegacyNodeの第二引数 deep が false のため、インポート元のノードの子ノード（p要素）はインポートされていません。\n";
61        echo "メインドキュメントのHTMLを確認し、追加されたdiv要素に子要素pが含まれていないことを確認してください。\n";
62    } catch (Dom\DOMException $e) {
63        // ノードの追加中にエラーが発生した場合
64        echo "ノードの追加中にエラーが発生しました: " . $e->getMessage() . "\n";
65        echo "これは、importLegacyNodeがノードのドキュメント所有者を適切に変更しなかった可能性があります。\n";
66    }
67}
68
69// サンプル関数を実行
70demonstrateImportLegacyNode();

Dom\HTMLDocument::importLegacyNodeメソッドは、異なるHTMLドキュメントで作成されたDOMノードを、現在のHTMLドキュメントのコンテキストへ適合させる（インポートする）ために使用されます。PHPにおけるimplementsは、クラスがインターフェースの契約を「実装する」ことを指しますが、このメソッドは、あるドキュメントで「実装された」（作成された）ノードを、現在のドキュメントに「実装し直す」（属させる）役割を担います。

このメソッドは、インポートしたいDom\Nodeオブジェクトを最初の引数に取ります。第二引数$deepは真偽値で、ノードの子孫も再帰的にインポートするかどうかを指定し、デフォルトはfalseです。メソッドの戻り値はありませんが、呼び出し後には渡されたノードの所有ドキュメントが、現在のHTMLDocumentに変更されます。

サンプルコードでは、まずメインとなるDom\HTMLDocumentと、ノードの供給元となるDom\HTMLDocumentをそれぞれ用意します。供給元ドキュメントでdiv要素とその子であるp要素を作成した後、importLegacyNodeメソッドを呼び出してdivノードをメインドキュメントにインポートしています。この際、$deepをfalseに設定したため、divノードの子孫であるp要素はインポートされません。インポートが完了したdivノードは、その後メインドキュメントのbody要素に手動で追加されます。このように、$deep引数の値によってインポートされる範囲が異なる点に注意が必要です。

Dom\HTMLDocument::importLegacyNodeは、別のHTMLドキュメントに属するノードを現在のドキュメントに適合させるためのメソッドです。ノードの所属は変更されますが、ドキュメントツリーには自動で追加されません。そのため、インポート後はappendChildなどで手動でノードを追加する必要があります。

特に注意すべきは第二引数$deepです。これをfalseにすると、元のノードの子孫ノードはインポートされず、本体ノードのみがインポートされます。子ノードも含めてインポートしたい場合はtrueを指定してください。このメソッドには戻り値がないため、呼び出し後はノードが現在のドキュメントに適合したことを前提に処理を進めます。「php implementsとは」は、通常インターフェースの実装を指しますが、ここではノードを現在のドキュメントの文脈に「再実装」すると捉えることができます。

関連コンテンツ

関連IT用語

関連プログラミング言語