Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

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

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

作成日: 更新日:

基本的な使い方

replaceChildrenメソッドは、呼び出し元であるDom\HTMLDocumentオブジェクトの全ての子ノードを、指定された新しいノードの集合に置き換えるメソッドです。このメソッドを使用すると、HTML文書全体を表現するDom\HTMLDocumentオブジェクトが現在持っている子要素(テキストや他のHTMLタグなど)を一度にすべて削除し、新しく渡された内容で完全に上書きすることができます。

具体的には、引数として一つ以上のDOMNodeオブジェクトや文字列を渡すことができます。DOMNodeオブジェクトを渡した場合は、それがそのまま新しい子ノードとして追加されます。文字列を渡した場合は、その文字列はテキストノードとして解釈され、HTML文書に追加されます。引数を何も渡さない場合は、既存の子ノードがすべて削除され、Dom\HTMLDocumentオブジェクトは子ノードを持たない状態になります。

この機能は、HTML文書のコンテンツを動的に完全に更新したい場合に非常に便利です。例えば、ユーザーの操作に応じてページのメインコンテンツ全体を入れ替えたり、初期表示後にサーバーから取得したデータで文書の内容をまるごと構築し直したりするシナリオで活用できます。既存の子ノードを手動で一つずつ削除してから新しいノードを追加する手間を省き、効率的にDOMを操作することが可能です。このメソッドはPHP 8で導入され、より現代的で直感的なDOM操作を提供します。

構文(syntax)

1<?php
2
3$document = new DOM\HTMLDocument();
4
5// 新しい HTML 要素を作成し、その中に body と p 要素を追加
6$htmlElement = $document->createElement('html');
7$bodyElement = $document->createElement('body');
8$bodyElement->appendChild($document->createElement('p', '新しいコンテンツです。'));
9$htmlElement->appendChild($bodyElement);
10
11// Dom\HTMLDocument の replaceChildren メソッドを呼び出し、
12// ドキュメントの既存の子ノード(もしあれば)を新しい HTML 要素で置き換える
13$document->replaceChildren($htmlElement);
14
15echo $document->saveHTML();
16
17?>

引数(parameters)

Dom\Node|string ...$nodes

  • Dom\Node|string $nodes: 置換する子ノード、またはHTML文字列を指定します。可変長引数です。

戻り値(return)

void

このメソッドは、要素のすべての子ノードを置き換えます。戻り値はありません。

サンプルコード

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

1<?php
2
3// Dom\HTMLDocument クラスを使用してHTMLドキュメントを操作する例です。
4// replaceChildren() メソッドを引数なしで呼び出すことで、
5// 特定の親ノードのすべての子ノードを削除する方法を示します。
6// これは、既存の子ノードをすべて「置き換え」る際に、新しい子ノードを指定しないことで、
7// 実質的にすべての既存の子ノードを削除する操作となります。
8
9// 1. 新しいHTMLドキュメントオブジェクトを作成します。
10$document = new Dom\HTMLDocument();
11
12// 2. ドキュメントに初期のHTMLコンテンツを読み込みます。
13//    ここでは、いくつかの要素を持つ<body>タグを含めます。
14$initialHtml = '
15<!DOCTYPE html>
16<html>
17<head>
18    <title>Remove Children Example</title>
19</head>
20<body>
21    <h1>Welcome!</h1>
22    <p>This is a paragraph inside the body.</p>
23    <div id="container">
24        <span>Child 1</span>
25        <span>Child 2</span>
26    </div>
27</body>
28</html>';
29$document->loadHTML($initialHtml);
30
31echo "--- Original HTML (before removing children) ---\n";
32// 変更前のHTMLコンテンツを出力します。
33echo $document->saveHTML();
34echo "\n\n";
35
36// 3. <body>要素を取得します。
37//    getElementsByTagName() は NodeList を返すため、item(0) で最初の要素を取得します。
38$bodyElement = $document->getElementsByTagName('body')->item(0);
39
40// 4. <body>要素が正しく取得できたか確認し、replaceChildren()を呼び出します。
41if ($bodyElement instanceof Dom\HTMLElement) {
42    echo "--- HTML after removing all children from <body> element ---\n";
43    // replaceChildren() を引数なしで呼び出すと、
44    // その要素のすべての子ノードが削除され、結果として要素が空になります。
45    $bodyElement->replaceChildren();
46    // 変更後のHTMLコンテンツを出力します。<body>タグの中が空になっていることを確認できます。
47    echo $document->saveHTML();
48} else {
49    echo "Error: Could not find the <body> element in the document.\n";
50}

PHP 8のDom\HTMLDocumentクラスに属するreplaceChildrenメソッドは、指定した親ノードのすべての子ノードを新しいノードに置き換えるための機能を提供します。このメソッドはDom\NodeオブジェクトまたはHTML文字列を可変長引数...$nodesとして受け取りますが、引数を何も渡さなかった場合、既存のすべての子ノードが削除され、親ノードは空の状態になります。戻り値はvoidで、直接的な値を返しませんが、ドキュメントの構造が変更されます。

サンプルコードでは、まず新しいHTMLドキュメントを作成し、いくつかの要素を含む初期HTMLコンテンツを読み込みます。次に、<body>要素を取得し、この<body>要素に対してreplaceChildren()メソッドを引数なしで呼び出しています。これにより、<body>タグ内にあった<h1>や<p>、<div>といったすべての子ノードが削除され、<body>要素は空になります。

この動作は、既存の子ノードを「何も新しいノードに置き換えない」ことで、結果的にすべての子ノードを削除する、という挙動として理解できます。HTMLドキュメントの一部を動的にクリアしたい場合や、コンテンツを完全に書き換えたい場合に非常に便利です。特に、特定の要素からすべての子要素を効率的に削除したい場面で活用できます。

このサンプルコードは、replaceChildren()メソッドを引数なしで呼び出し、特定の親ノードのすべての子ノードを削除する方法を示しています。これは既存の子ノードを新しい子ノードで「置き換える」際に、新しい子ノードを何も指定しないことで、すべての既存の子ノードを削除する操作となります。

注意点として、引数なしでは対象ノード内のすべての子ノードが削除されるため、部分的に削除したい場合は別の方法を検討してください。また、操作対象となる親ノードは、getElementsByTagNameなどで正確に取得し、要素が存在するか確認してからメソッドを呼び出すことが重要です。メソッドの戻り値はvoidで、何も返されません。意図しないHTML要素を操作しないよう、対象ノードの確認を必ず行いましょう。

PHP DomDocument::replaceChildren で子要素を置き換える

1<?php
2
3/**
4 * Dom\HTMLDocument::replaceChildren メソッドの使用例。
5 *
6 * このメソッドは、ターゲットノードの全ての子ノードを、提供された新しいノード群で置き換えます。
7 * Dom\HTMLDocument クラスのインスタンスもこのメソッドを持ちますが、
8 * 一般的には、ドキュメント内の特定の要素(例:<body>)の子ノードを操作する際に使用されます。
9 */
10function demonstrateHtmlDocumentReplaceChildren(): void
11{
12    // 1. Dom\HTMLDocument オブジェクトを作成し、初期HTMLコンテンツをロードします。
13    // PHP 8 の Dom 拡張を使用しています。
14    $document = new Dom\HTMLDocument();
15    $initialHtml = '<!DOCTYPE html><html><head><title>Original Title</title></head><body><p>First paragraph</p><span>Original span</span><p>Second paragraph</p></body></html>';
16    $document->loadHTML($initialHtml);
17
18    echo "--- Original HTML Document ---" . PHP_EOL;
19    echo $document->saveHTML() . PHP_EOL . PHP_EOL;
20
21    // 2. ドキュメントから <body> 要素を取得します。
22    // Dom\HTMLDocument::querySelector() は、CSSセレクタを使用して要素を検索します。
23    $bodyElement = $document->querySelector('body');
24
25    if ($bodyElement) {
26        // 3. 新しい子ノードとして使用する Dom\Element オブジェクトと文字列を作成します。
27        // replaceChildren は Dom\Node オブジェクトと文字列の両方を受け入れ、
28        // 文字列は自動的に Dom\Text ノードとして扱われます。
29        $newHeading = $document->createElement('h1', 'New Heading');
30        $newParagraph = $document->createElement('p', 'This is a new paragraph replacing the old content.');
31        $newTextContent = 'Additional new text content.';
32
33        // 4. <body> 要素の既存の子ノードを全て、上記で作成した新しいノード群で置き換えます。
34        // 引数には、置き換えたい新しいノードを任意の数だけ指定できます。
35        $bodyElement->replaceChildren($newHeading, $newParagraph, $newTextContent);
36
37        echo "--- HTML Document After replaceChildren ---" . PHP_EOL;
38        echo $document->saveHTML() . PHP_EOL;
39    } else {
40        echo "Error: <body> element not found." . PHP_EOL;
41    }
42}
43
44// 関数を実行します。
45demonstrateHtmlDocumentReplaceChildren();
46

PHP 8で提供されるDom拡張機能の一つであるreplaceChildrenメソッドは、指定したHTML要素のすべての子ノードを、新しく指定されたノード群で置き換えるための機能です。このメソッドは、Dom\HTMLDocumentクラスだけでなく、HTMLドキュメント内の特定の要素(Dom\Elementオブジェクトなど)に対しても利用できます。

具体的には、既存のHTML要素の子要素やテキストコンテンツを全て削除し、代わりに引数で渡された複数のDom\Nodeオブジェクトや文字列を新しい子ノードとして追加します。引数として文字列を渡した場合、それは自動的にテキストノードとして扱われます。例えば、Webページの一部を動的に更新する際や、特定のセクションのコンテンツを丸ごと入れ替えるような場合に非常に役立ちます。

このメソッドの引数には、新しい子ノードとして追加したいDom\Nodeオブジェクト(例:h1要素、p要素など)や、単なるテキストコンテンツを表す文字列をいくつでも指定できます。戻り値はvoidであり、メソッドが実行されると、呼び出し元のHTML要素の内部構造が直接変更されます。これにより、php replace関数というキーワードが示すように、PHPでDOMを操作し、特定の子ノードを効率的に置き換えることが可能となります。

このreplaceChildrenメソッドは、対象のHTML要素が持つ全ての子ノードを、指定された新しいノード群で完全に置き換える機能です。既存の内容を部分的に変更するのではなく、全体を新しい内容に上書きするため、操作の範囲をよく理解してください。引数には、HTML要素として扱うDom\Nodeオブジェクトと、単なるテキストとして扱う文字列の両方を複数指定できます。PHPにおける一般的な文字列置換関数とは異なり、本メソッドはHTML文書の構造(DOM)を直接操作します。そのため、目的の要素が確実に選択できているか、querySelectorの戻り値を適切に確認することが、安全なコードのために非常に重要です。

関連コンテンツ

関連プログラミング言語