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

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

作成日: 2025年09月11日更新日: 2026年02月12日

基本的な使い方

replaceWithメソッドは、DOMツリー上の子ノードを他のノードやテキストで置き換えることを実行するメソッドです。

このメソッドは、Webページの構造を表現するDOM（Document Object Model）ツリーにおいて、呼び出し元であるDOMChildNodeのインスタンス、例えばHTMLの特定の要素やテキストノードなどを、指定された新しいコンテンツで置き換えるために使用されます。具体的には、対象となるノードが自身の親ノードから削除され、その削除された位置に引数として渡された新しいノードや文字列が挿入されます。

replaceWithメソッドは複数の引数を受け取ることができ、それらの引数は指定された順序で元のノードがあった場所に挿入されます。これにより、一つの既存ノードを複数の新しいノードやテキストで一度に置き換えるといった柔軟な操作が可能です。引数として文字列を渡した場合、その文字列は自動的に新しいテキストノードとして扱われ、DOMツリーに挿入されるため、テキスト内容の更新や追加も手軽に行えます。

この機能は、Webアプリケーションで動的にページのコンテンツを更新する際に特に役立ちます。例えば、表示されている古い情報を新しい情報に置き換えたり、ユーザーの操作に応じて特定の要素の見た目や機能を別のものに完全に変更したりする場面などで利用されます。既存のノードを一度削除して新しいノードを挿入するという一連の操作を簡潔に記述できるため、Webページの動的な操作を効率的に行うための重要なメソッドの一つです。

構文(syntax)


1<?php
2
3// DOMDocumentインスタンスを作成し、HTMLコンテンツを読み込む
4$dom = new DOMDocument();
5$dom->loadHTML('<div><p>Hello <span id="target">World</span>!</p></div>');
6
7// 置き換え対象となるDOMChildNodeのインスタンスを取得（例: id="target" のspan要素）
8$targetNode = $dom->getElementById('target');
9
10// 対象ノードが存在する場合
11if ($targetNode) {
12    // 置き換えるための新しいDOMNodeのインスタンスや文字列を作成
13    $newNode1 = $dom->createElement('strong', 'PHP'); // 新しい<strong>要素
14    $newNode2 = $dom->createElement('em', 'programming'); // 新しい<em>要素
15    $newText = 'language'; // 新しいテキストコンテンツ
16
17    // DOMChildNode::replaceWith メソッドの構文
18    // 既存のノード($targetNode)を、指定された複数のノードや文字列で置き換える
19    // 引数にはDOMNodeオブジェクトまたは文字列を、可変長で指定できる
20    $targetNode->replaceWith($newNode1, $newNode2, $newText);
21}
22
23?>

引数(parameters)

DOMNode|string ...$nodes

DOMNode|string $nodes: 置換する新しいノードまたはノードの配列、あるいはHTML文字列

戻り値(return)

void

このメソッドは、呼び出し元のノードを、引数として渡されたノードまたはノードのリストで置き換えます。戻り値はありません。

サンプルコード

PHP DOM replaceWithで要素を置き換える


1<?php
2
3// DOMDocument オブジェクトを作成
4// HTML5の推奨に合わせてDOCTYPEや<head>, <body>タグを自動生成しない設定
5$dom = new DOMDocument('1.0', 'UTF-8');
6$dom->loadHTML('<div><p>こんにちは、世界！</p><p class="target-paragraph">ここは置き換え対象の段落です。</p><p>また会いましょう。</p></div>', LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
7
8// XPath を使用して、特定の要素（クラス名が 'target-paragraph' の p 要素）を検索
9$xpath = new DOMXPath($dom);
10$targetNode = $xpath->query('//p[@class="target-paragraph"]')->item(0);
11
12// 対象ノードが正常に見つかった場合のみ処理を実行
13if ($targetNode instanceof DOMChildNode) {
14    // 新しい HTML 要素を作成
15    $newNode = $dom->createElement('span', '新しいスパン要素がここに来ました！');
16    $newNode->setAttribute('style', 'color: blue; font-weight: bold;');
17
18    // DOMChildNode::replaceWith() メソッドを使用して、既存のノードを新しいノードで置き換える
19    // 引数には DOMNode オブジェクトや HTML 文字列を複数指定可能
20    $targetNode->replaceWith($newNode);
21
22    // 変更後の HTML を出力
23    echo $dom->saveHTML();
24} else {
25    echo "置き換え対象のノードが見つかりませんでした。\n";
26}
27

PHPのDOMChildNode::replaceWith()メソッドは、Webページの構造を構成する既存のDOMノードを、指定した新しいノードやHTML文字列に置き換える際に使用する機能です。これは、HTMLの内容をプログラムで動的に変更したい場合に役立ちます。

サンプルコードでは、まずHTMLからDOMDocumentオブジェクトを作成し、その中から特定のクラス名（target-paragraph）を持つタグをXPathを使って検索し、置き換え対象としています。

次に、$dom->createElement()メソッドで「新しいスパン要素がここに来ました！」というテキストを持つ新しい要素を作成し、スタイルを設定しています。

そして、$targetNode->replaceWith($newNode);という行が、このメソッドの核となる部分です。ここでは、先ほど検索した既存のタグを、作成した新しい要素に置き換えています。replaceWith()メソッドの引数には、DOMNodeオブジェクトの他、HTML文字列を直接指定することもでき、さらに複数の要素を一度に指定して置き換えることも可能です。このメソッドはノードを置き換える操作のみを行い、戻り値はvoid、つまり何も返しません。

コードの実行結果として、元のHTMLで「ここは置き換え対象の段落です。」と書かれていたタグが、新しいタグに置き換わったHTMLが出力されます。これにより、プログラムを通じてHTML要素を柔軟に操作できることを確認できます。

DOMChildNode::replaceWithは、指定したノードを新しいHTML要素やHTML文字列に置き換えるメソッドです。引数にはDOMNodeオブジェクトの他に、HTML文字列も複数指定できます。文字列を渡す際は、それが有効なHTMLとして正しく解釈されるよう注意が必要です。

このメソッドは戻り値がないため、置き換え対象のノードが実際に存在するかを事前に確認することが大切です。サンプルコードのようにif文で確認し、予期せぬ挙動を防ぎましょう。

外部からの入力を文字列として直接渡す場合、悪意のあるHTMLが挿入されるクロスサイトスクリプティング（XSS）のリスクがあります。信頼できないデータは、安全のために必ず適切に無害化（サニタイズ）してから利用してください。元のノードは置き換えによってDOMツリーから完全に削除されます。