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

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

作成日: 2025年09月11日更新日: 2025年11月03日

基本的な使い方

replaceChildrenメソッドは、DOM (Document Object Model) の Dom\Document クラスに属するメソッドで、指定されたノードの子ノードを、新しいノードで置き換える処理を実行します。具体的には、このメソッドは、Dom\Document オブジェクトが表すドキュメントの特定ノードの子要素を全て削除し、引数として渡されたノード（またはノードのリスト）を、そのノードの新しい子要素として追加します。

このメソッドを使用することで、既存のXMLやHTMLドキュメント構造を、プログラム的に動的に変更することが可能になります。例えば、特定の条件に基づいてドキュメントの一部を更新したり、新しいコンテンツを挿入したりする際に役立ちます。

replaceChildrenメソッドは、引数としてノードオブジェクトまたはノードオブジェクトのリストを受け取ります。これらのノードが、置換対象のノードの新しい子ノードとなります。引数を何も指定しない場合、置換対象ノードの子ノードはすべて削除されます。

このメソッドは、DOM操作の中核的な部分を担っており、XMLやHTMLドキュメントを扱うPHPアプリケーションにおいて、ドキュメント構造の動的な操作を実現するための重要なツールとなります。システムエンジニアがWebアプリケーション開発を行う際、ユーザーからのリクエストに応じて動的にHTMLコンテンツを生成したり、XMLデータを処理して必要な情報を抽出・加工したりする場面で、このメソッドを活用することで、効率的かつ柔軟なシステム構築が可能となります。

構文(syntax)


1<?php
2
3namespace Dom;
4
5class Document
6{
7    public function replaceChildren(DOMNode ...$nodes): void {}
8}

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string ...$nodes: 置換する新しいノードまたはノードの配列、あるいはHTML文字列を指定します。

戻り値(return)

Dom\Element

このメソッドは、対象のDOM要素の子要素を、指定された新しい子要素のリストで置き換えた結果として、変更されたDOM要素自身を返します。

サンプルコード

PHP DomDocument::replaceChildrenで子ノードを削除する


1<?php
2
3/**
4 * Dom\Document::replaceChildren メソッドを使用して、要素のすべての子ノードを削除する例。
5 *
6 * このメソッドは既存の子ノードを新しいノードで置き換えるために使用されます。
7 * 引数を一切渡さない場合、既存の子ノードはすべて削除されます。
8 */
9function removeAllChildrenExample(): void
10{
11    // 1. 新しい Dom\Document オブジェクトを作成します。
12    $dom = new Dom\Document();
13
14    // 2. サンプルとなるHTMLをロードします。
15    // loadHTML はドキュメントの内部エンコーディングを自動検出します。
16    $htmlContent = <<<HTML
17<!DOCTYPE html>
18<html>
19<head>
20    <title>PHP DOM Example</title>
21</head>
22<body>
23    <h1>DOM操作の例</h1>
24    <div id="targetContainer">
25        <p>これは削除されるべき最初のパラグラフです。</p>
26        <span>これは削除されるべきスパン要素です。</span>
27        <p>これも削除されるべき最後のパラグラフです。</p>
28    </div>
29    <div id="anotherContainer">
30        <span>このコンテナの内容は変更されません。</span>
31    </div>
32</body>
33</html>
34HTML;
35    $dom->loadHTML($htmlContent);
36
37    // 3. 子ノードを削除したい要素（ここではIDが 'targetContainer' のdiv要素）を取得します。
38    // Dom\Document::getElementById は、指定されたIDを持つ要素を Dom\Element オブジェクトとして返します。
39    $targetElement = $dom->getElementById('targetContainer');
40
41    if ($targetElement) {
42        echo "--- 変更前の 'targetContainer' 要素の内容 ---\n";
43        // saveHTML は、指定されたノードのHTML文字列を返します。
44        echo $dom->saveHTML($targetElement) . "\n\n";
45
46        // 4. replaceChildren() を呼び出して、'targetContainer' のすべての子ノードを削除します。
47        // 引数を何も渡さない場合、既存の子ノードは全て削除され、新しい子ノードは追加されません。
48        // このメソッドは Dom\Element (ここでは $targetElement 自身) を返しますが、今回はその戻り値は使用しません。
49        $targetElement->replaceChildren();
50
51        echo "--- 変更後の 'targetContainer' 要素の内容 ---\n";
52        echo $dom->saveHTML($targetElement) . "\n\n";
53
54        echo "--- ドキュメント全体の最終状態 (<body>要素) ---\n";
55        // ドキュメント全体がどのように変更されたかを確認するために、<body>要素の内容を出力します。
56        $body = $dom->getElementsByTagName('body')->item(0);
57        if ($body) {
58            echo $dom->saveHTML($body) . "\n";
59        }
60    } else {
61        echo "エラー: ID 'targetContainer' を持つ要素が見つかりませんでした。\n";
62    }
63}
64
65// 関数を実行して、子ノード削除の動作を確認します。
66removeAllChildrenExample();
67

PHPのDOM操作において、Dom\Document::replaceChildrenメソッドは、指定した要素の子ノードを操作するために使用されます。このメソッドの主な役割は、既存の子ノードを新しく指定されたノードで置き換えることです。

引数には、新しく追加したい子ノードをDom\NodeオブジェクトまたはHTML文字列として複数渡すことができます。しかし、このメソッドの非常に便利な使い方として、引数を何も渡さない場合、その要素の既存の子ノードはすべて削除されます。これにより、要素のコンテンツを完全にクリアしたい場合に役立ちます。メソッドの戻り値は、操作を行ったDom\Elementオブジェクト自身です。

提供されたサンプルコードでは、まずDom\Documentオブジェクトを作成し、HTMLコンテンツをロードしています。次に、IDが「targetContainer」のdiv要素を取得し、そのDom\Elementオブジェクトに対してreplaceChildren()メソッドを引数なしで呼び出しています。この操作により、「targetContainer」内に存在していたすべてのパラグラフやスパン要素といった子ノードが完全に削除されます。実行結果を見ると、replaceChildren()呼び出し前には子ノードが存在していたtargetContainerの中身が空になっていることが確認できます。このように、replaceChildren()メソッドを引数なしで使用することで、特定の要素から全ての子ノードを効率的に、かつ簡潔に削除することが可能です。

このサンプルコードで利用されているreplaceChildren()メソッドは、引数を一切渡さない場合に限り、対象要素内のすべての子ノードを削除します。特定のノードだけを削除したい場合は、別のDOM操作メソッドを検討してください。このメソッドはDom\Documentではなく、Dom\Elementインスタンスに対して呼び出すものであり、ドキュメント内の特定の要素の子ノードを操作するために使用します。getElementById()で要素を取得する際は、HTML内のIDが一意であることを確認すると、意図しない要素を操作するリスクを減らせます。また、loadHTML()でHTMLをロードする際に、文字化けなどの問題が発生する場合は、エンコーディングを明示的に指定することを検討すると、より安全に利用できます。本来replaceChildren()は、既存の子ノードを新しいノードで置き換える機能も持っていることを理解しておくと、様々なDOM操作に応用できます。

PHP DomDocument::replaceChildrenで子ノードを置換する


1<?php
2
3// Dom\Document::replaceChildren の使用例
4// このメソッドは、Dom\Documentオブジェクトの直下にある全ての子ノードを、
5// 指定された新しいノードまたはHTML文字列で置き換えます。
6// 通常、これはHTMLドキュメントのルート要素（例えば <html> タグ）
7// そのものを置き換える操作に相当します。
8// そのため、標準的なHTML文書の構造が維持されない可能性がある点に注意が必要です。
9
10// 新しい Dom\Document インスタンスを作成します。
11$dom = new \Dom\Document();
12
13// 出力時にHTMLを整形するための設定
14$dom->formatOutput = true;
15$dom->preserveWhiteSpace = false; // 空白を保持しない設定
16
17// ドキュメントに初期のHTMLコンテンツをロードします。
18// ここでは基本的なHTML5文書構造を想定しています。
19$initialHtml = '<!DOCTYPE html><html><head><title>Original Document</title></head><body><h1>Hello, World!</h1><p>This is the original content.</p></body></html>';
20$dom->loadHTML($initialHtml);
21
22// 置換前のドキュメントのHTMLコンテンツを出力して確認します。
23echo "--- 元のドキュメント ---\n";
24echo $dom->saveHTML();
25echo "\n";
26
27// Dom\Document::replaceChildren メソッドを呼び出して、
28// ドキュメントの直下の子ノード（この場合は <html> 要素）を置き換えます。
29// 新しいコンテンツは単純な div 要素とその中のテキストとします。
30$newContentHtml = '<div><h2>New Root Content</h2><p>This entirely replaces the previous HTML root element.</p></div>';
31$replacedElement = $dom->replaceChildren($newContentHtml);
32
33// 置換後のドキュメントのHTMLコンテンツを出力して確認します。
34echo "--- replaceChildren 後のドキュメント ---\n";
35echo $dom->saveHTML();
36echo "\n";
37
38// replaceChildren メソッドは、新しく追加された要素の Dom\Element インスタンスを返します。
39// この例では、新しく作成された <div> 要素のインスタンスが返されます。
40echo "--- replaceChildren が返した要素情報 ---\n";
41echo "タグ名: " . $replacedElement->tagName . "\n";
42echo "ノードタイプ: " . $replacedElement->nodeName . "\n";
43
44?>

Dom\Document::replaceChildrenメソッドは、Dom\Documentオブジェクト直下の全ての子ノードを、指定された新しいノードやHTML文字列で置き換える機能です。通常、この操作はHTMLドキュメントのルート要素全体を置き換えることに相当するため、標準的なHTML文書構造が維持されない可能性がある点に注意が必要です。

引数には、新しいコンテンツとなるDom\Nodeオブジェクト、またはHTML文字列を複数指定できます。メソッドは、置き換えによりドキュメントに追加された新しいDom\Elementインスタンスを戻り値として返します。

サンプルコードでは、初期のHTMLドキュメントがロードされた後、replaceChildrenメソッドを使用してそのルートコンテンツ全体を<div>要素を含むHTML文字列に置き換えています。この操作により、元の<html>要素と全ての子ノードは削除され、ドキュメントの唯一の子ノードとして新しい<div>要素が配置されます。置き換え後のドキュメント内容と、メソッドが返した<div>要素の情報から、この挙動を確認できます。

このDom\Document::replaceChildrenメソッドは、HTMLドキュメントの直下にある全ての子ノード、通常は<html>タグ全体を置き換える特殊な機能です。そのため、<head>や<body>といった標準的なHTML文書構造が失われ、非標準なドキュメント構造になる可能性があることに注意が必要です。

引数にHTML文字列を渡した場合、その文字列がDOMノードとしてパースされ、ドキュメントの新しいルート要素となります。このメソッドは、新しく追加された要素のDom\Elementインスタンスを返しますので、その後の操作に利用できます。一般的な文字列置換関数とは異なり、これはDOMツリーの構造そのものを操作するメソッドであることを理解して利用してください。文書構造が大きく変わるため、利用目的を明確にし、影響範囲を十分に確認することが重要です。