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

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

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

基本的な使い方

replaceChildrenメソッドは、DOMElementオブジェクトのすべての子ノードを削除し、指定された新しいノードまたはノード群に置き換える処理を実行するメソッドです。このメソッドを呼び出すと、まず対象となるDOMElementインスタンスが現在持っているすべての子ノードが完全にクリアされます。その後、引数として渡された新しいノード（DOMNodeオブジェクト）やノードの配列が、そのDOMElementの子ノードとして指定された順序で追加されます。

もし引数に何もノードが渡されなかった場合、そのDOMElementからはすべての子ノードが削除されるだけで、新しい子ノードは追加されません。この機能により、Webページなどの動的なUI更新において、要素のコンテンツを効率的かつ一度の操作で完全に更新することが可能になります。既存の子ノードを一つずつ削除し、その後新しいノードを一つずつ追加するといった複数のステップを、このメソッド一つで完結できるため、コードの可読性を高め、処理の簡素化にも貢献します。PHP 8.0で導入されたこのメソッドは、DOM操作における一般的なパターンをより直感的かつ効率的に記述するための重要な機能の一つです。

構文(syntax)


1<?php
2$dom = new DOMDocument();
3$parentElement = $dom->createElement('container');
4$dom->appendChild($parentElement);
5
6// 既存の子要素を親要素に追加
7$parentElement->appendChild($dom->createElement('old_item', 'Item A'));
8$parentElement->appendChild($dom->createElement('old_item', 'Item B'));
9
10// 新しい子要素を作成
11$newItem1 = $dom->createElement('new_item', 'Item X');
12$newItem2 = $dom->createElement('new_item', 'Item Y');
13
14// 既存の全ての子要素を、指定された新しい子要素で置き換える
15$parentElement->replaceChildren($newItem1, $newItem2);

引数(parameters)

?DOMNode ...$nodes

?DOMNode ...$nodes: 既存の子ノードを置き換えるための、0個以上のDOMNodeオブジェクトまたはnull。可変長引数として指定します。

戻り値(return)

DOMNode|false

このメソッドは、要素の子ノードをすべて新しいノードリストで置き換えた場合、成功したDOMNodeオブジェクトを返します。置き換えに失敗した場合はfalseを返します。

サンプルコード

PHP: DOMElement::replaceChildrenで子要素を削除する


1<?php
2
3/**
4 * DOMElement::replaceChildren() メソッドを使用して、
5 * 指定されたHTML要素の全ての子ノードを削除するサンプルです。
6 *
7 * この関数は、システムエンジニアを目指す初心者向けに、
8 * DOM操作の基本的な流れとreplaceChildren()の利用方法を示します。
9 */
10function removeAllChildrenFromElementExample(): void
11{
12    // 1. DOMDocument オブジェクトを作成します。
13    //    HTML ドキュメントを解析し、操作するために必要です。
14    $dom = new DOMDocument('1.0', 'UTF-8');
15
16    // エラー発生時の警告を抑制し、内部エラーとして扱います。
17    // 初心者向けには必須ではありませんが、実用的なコードでよく使われます。
18    libxml_use_internal_errors(true);
19
20    // 2. 操作対象となるHTML文字列を読み込みます。
21    //    ここでは、子要素を持つdiv要素を含む簡単なHTMLを用意します。
22    $htmlContent = '
23        <!DOCTYPE html>
24        <html>
25        <head>
26            <title>DOMElement::replaceChildren Example</title>
27        </head>
28        <body>
29            <h1>子要素削除の例</h1>
30            <div id="myContainer">
31                <p>これは削除されるべき最初の段落です。</p>
32                <span>これは削除されるべきスパン要素です。</span>
33                <ul>
34                    <li>リストアイテム1</li>
35                    <li>リストアイテム2</li>
36                </ul>
37                <p>これも削除されるべき最後の段落です。</p>
38            </div>
39            <div id="anotherContainer">
40                <p>このコンテナの子要素は削除されません。</p>
41            </div>
42        </body>
43        </html>
44    ';
45    $dom->loadHTML($htmlContent);
46
47    // 3. ターゲットとなるHTML要素を ID で取得します。
48    //    ここでは、IDが "myContainer" の div 要素を対象とします。
49    $targetElement = $dom->getElementById('myContainer');
50
51    // ターゲット要素が正常に取得できたかを確認します。
52    if ($targetElement instanceof DOMElement) {
53        echo "--- 処理前のターゲット要素の状態 ---\n";
54        // saveHTML() に要素を渡すことで、その要素と子孫のHTMLを文字列として取得できます。
55        echo $dom->saveHTML($targetElement);
56        echo "\n\n";
57
58        // 4. DOMElement::replaceChildren() メソッドを使用して、
59        //    ターゲット要素の全ての子ノードを削除します。
60        //    引数を何も渡さない場合、既存の全ての子ノードが削除されます。
61        //    戻り値は削除された最初のノードか false ですが、この用途では通常利用しません。
62        $targetElement->replaceChildren();
63
64        echo "--- replaceChildren() 実行後のターゲット要素の状態 ---\n";
65        echo $dom->saveHTML($targetElement);
66        echo "\n\n";
67
68        echo "--- ドキュメント全体のHTML（変更後） ---\n";
69        // ドキュメント全体のHTMLを確認し、変更が反映されていることを確認します。
70        echo $dom->saveHTML();
71        echo "\n";
72    } else {
73        echo "エラー: ID 'myContainer' を持つターゲット要素が見つかりませんでした。\n";
74    }
75
76    libxml_clear_errors(); // 内部エラーのクリア
77}
78
79// 上記のサンプル関数を実行します。
80removeAllChildrenFromElementExample();

このPHPサンプルコードは、DOMElementクラスのreplaceChildren()メソッドを用いて、指定したHTML要素の全ての子ノードを削除する方法を示しています。システムエンジニアを目指す初心者の方にも、DOM（Document Object Model）を操作する基本的な流れと、特定の要素から子ノードを一括で削除する具体的な手法を理解いただくことを目的としています。

まず、DOMDocumentオブジェクトを作成し、操作したいHTML文字列を読み込みます。これにより、HTMLドキュメントがメモリ上にツリー構造として表現され、PHPから各要素をオブジェクトとして扱えるようになります。次に、getElementById()メソッドでIDを指定して、子ノードを削除したいターゲットのHTML要素（div要素）を取得します。

ターゲット要素が取得できた後、その要素に対してreplaceChildren()メソッドを呼び出します。このメソッドは、引数に?DOMNode ...$nodesとありますが、引数を何も渡さない場合、ターゲット要素が持つ既存の全ての子ノードを削除し、新しい子ノードを追加しないという挙動になります。これにより、指定した要素の中身を空にすることが可能です。メソッドの戻り値はDOMNode|falseで、削除された最初のノードが返されるか、失敗した場合はfalseが返りますが、全ての子ノードを削除するこの用途では通常、戻り値の確認は行いません。

実行前と実行後のHTML出力を比較することで、replaceChildren()メソッドの呼び出しにより、myContainer要素内の<p>, <span>, <ul>などの全ての子ノードが完全に削除されたことを確認できます。このサンプルは、Webページの一部を動的にクリアするといったDOM操作の基礎として役立ちます。

DOMElement::replaceChildren()メソッドは、引数なしで呼び出すと対象要素の全ての子ノードを削除しますが、引数を渡すと既存の子ノードを削除し、指定された新しいノードで置き換える点に注意が必要です。意図しない要素の削除を防ぐため、引数の有無による挙動の違いをしっかり理解してください。このメソッドの戻り値は削除された最初のノードかfalseですが、単に子ノードを削除する目的では通常は利用しません。DOMDocumentでHTMLをロードした後、getElementById()などで操作対象の要素を正確に取得することが重要です。要素が見つからない場合は操作が実行されません。サンプルコードにあるlibxml_use_internal_errors(true)はHTML解析時の警告を抑制するためのもので、学習中はエラーメッセージを確認できるよう、まずはこの設定なしで試すこともお勧めします。この操作はメモリ上のDOMツリーを変更するものであり、元のHTMLファイルには直接影響しない点もご留意ください。

PHP replaceChildrenで要素の子ノードを置き換える


1<?php
2
3// DOMElement::replaceChildren() メソッドの使用例
4// 指定された DOMElement の全ての子ノードを削除し、0個以上の新しい DOMNode オブジェクトで置き換えます。
5// このメソッドは、要素内のコンテンツを一度に完全に変更する際に非常に便利です。
6function demonstrateReplaceChildren(): void
7{
8    // DOMDocument を作成し、XML ヘッダとエンコーディングを指定します。
9    // formatOutput を true に設定することで、出力されるXMLを見やすく整形します。
10    $dom = new DOMDocument('1.0', 'UTF-8');
11    $dom->formatOutput = true;
12
13    // ルート要素 <div> を作成し、DOMDocument に追加します。
14    $parentElement = $dom->createElement('div');
15    $dom->appendChild($parentElement);
16
17    // 置き換え前の最初の子ノードを作成し、親要素に追加します。
18    $childP = $dom->createElement('p', 'これは最初の段落です。');
19    $childSpan = $dom->createElement('span', 'これは最初のスパンです。');
20    $parentElement->appendChild($childP);
21    $parentElement->appendChild($childSpan);
22
23    echo "--- replaceChildren() 呼び出し前の状態 ---\n";
24    // 現在の DOM 構造を XML 形式で出力します。
25    // この時点では、<div>要素内に2つの子ノード(<p>と<span>)が存在します。
26    echo $dom->saveXML();
27    echo "\n";
28
29    // 新しい子ノードを作成します。これらのノードが既存の子ノードと置き換わります。
30    $newChildStrong = $dom->createElement('strong', 'これは新しい強調されたテキストです。');
31    $newChildEm = $dom->createElement('em', 'これは新しいイタリックテキストです。');
32    // テキストノードも DOMNode の一種として直接渡すことができます。
33    $newChildText = $dom->createTextNode('これは新しいプレーンテキストです。');
34
35    // $parentElement の全ての子ノードを、新しく作成したノードで置き換えます。
36    // replaceChildren() の引数に渡すノードが0個の場合（例: $parentElement->replaceChildren()）、
37    // 全ての子ノードが削除され、親要素は空になります。
38    // メソッドの戻り値は、削除された DOMNode か、失敗時に false を返します。
39    // ここでは戻り値は特に利用しませんが、エラーハンドリングなどに利用できます。
40    $removedChildren = $parentElement->replaceChildren($newChildStrong, $newChildEm, $newChildText);
41
42    echo "--- replaceChildren() 呼び出し後の状態 ---\n";
43    // 置き換え後の DOM 構造を XML 形式で出力します。
44    // <div>要素の子ノードが、新しく作成した<strong>、<em>、テキストノードに置き換わっていることを確認できます。
45    echo $dom->saveXML();
46    echo "\n";
47}
48
49// 定義した関数を実行します。
50demonstrateReplaceChildren();
51

PHPのDOMElement::replaceChildren()メソッドは、HTMLやXMLのような文書構造（DOM）を操作する際に、ある要素の子ノードをまとめて置き換えるための機能です。このメソッドは、指定されたDOMElementの持つ既存の全ての子ノードを削除し、代わりに引数として渡された0個以上の新しいDOMNodeオブジェクトで置き換えます。例えば、ウェブページ上の特定の<div>タグの中身を完全に新しい内容に更新したい場合に非常に便利です。

引数には?DOMNode ...$nodesとあり、これは新しい子ノードとして追加したいDOMNodeオブジェクトを0個以上、複数指定できることを意味します。要素ノードやテキストノードなどを自由に渡すことが可能です。もし引数を何も渡さなかった場合（例: $element->replaceChildren();）、その要素の全ての子ノードが削除され、要素は空の状態になります。

戻り値はDOMNodeまたはfalseです。成功した場合は削除された子ノード（群）を返し、処理が失敗した場合にはfalseを返します。この戻り値を利用して、置き換え処理が正しく行われたかを確認することができます。

サンプルコードでは、まず親となる<div>要素に2つの子ノード（<p>と<span>）を追加し、その状態を確認しています。次に、replaceChildren()メソッドを使って、既存の<p>と<span>を、新しく作成した<strong>、<em>、そしてテキストノードで置き換える様子が示されています。これにより、要素のコンテンツを一括で効率的に更新する方法を理解できます。

DOMElement::replaceChildren()メソッドは、対象要素の既存の子ノードを全て削除し、引数に指定された新しいDOMNodeオブジェクトで完全に置き換えます。そのため、意図せず重要なコンテンツを失わないよう、置き換え対象の子ノードを事前に確認することが非常に重要です。

引数にノードを一つも渡さない場合、全ての子ノードが削除され、対象要素は空になります。新しい子ノードとして渡せるのは、DOMElementやDOMTextのようなDOMNode型のオブジェクトのみです。文字列を直接引数に指定することはできませんのでご注意ください。新しいノードを作成する際は、必ず親要素と同じDOMDocumentオブジェクトのcreateElement()やcreateTextNode()メソッドを使用してください。

戻り値は、削除されたDOMNodeまたは失敗時にfalseを返しますので、エラー処理に利用できます。このメソッドは要素内のコンテンツを一括で変更する際に便利ですが、既存コンテンツの完全な置き換えであることを常に意識して利用してください。