【PHP8.x】replaceWithメソッドの使い方

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

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

基本的な使い方

replaceWithメソッドは、DOMツリー内の特定の要素を、指定した一つ以上の新しいノードまたは文字列で置き換える処理を実行するメソッドです。このメソッドは、呼び出し元のDOMElementオブジェクトをドキュメントから削除し、その位置に引数で指定されたノード群を挿入します。引数には、DOMNodeオブジェクトやプレーンな文字列を複数指定することが可能です。引数に文字列を渡した場合、その文字列は自動的にテキストノードとして扱われ、HTMLタグとして解釈されることはありません。この操作により、元の要素はDOMツリーから完全に切り離されます。例えば、特定の段落要素を、別の見出し要素とテキストノードの組み合わせに差し替えるといった動的なコンテンツ操作に役立ちます。なお、このメソッドは親ノードを持たない要素に対して呼び出されるとDOMExceptionをスローするため、注意が必要です。処理が成功しても戻り値はなく、DOMツリーへの変更が直接行われます。

構文(syntax)


1<?php
2// HTML文字列を準備
3$html = <<<HTML
4<!DOCTYPE html>
5<html>
6<body>
7  <div id="container">
8    <p id="target">この要素が置き換えられます。</p>
9  </div>
10</body>
11</html>
12HTML;
13
14// DOMDocumentオブジェクトを作成し、HTMLを読み込む
15$dom = new DOMDocument();
16$dom->loadHTML($html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
17
18// 置き換え対象の要素を取得
19$targetElement = $dom->getElementById('target');
20
21// 新しい要素を作成
22$newElement = $dom->createElement('h1', '新しい見出し');
23$newTextNode = $dom->createTextNode('と、新しいテキストノード');
24
25// 対象の要素を、新しい要素とテキストノードで置き換える
26if ($targetElement) {
27    $targetElement->replaceWith($newElement, $newTextNode);
28}
29
30// 変更後のHTMLを出力
31echo $dom->saveHTML();
32?>

引数(parameters)

DOMNode|string ...$nodes

DOMNode|string ...$nodes: 置換する新しいノードまたはHTML文字列のリスト。省略可能です。

戻り値(return)

void

このメソッドは、要素を別の要素と置き換えますが、戻り値はありません。

サンプルコード

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


1<?php
2
3// DOMDocumentオブジェクトを初期化します。
4// これにより、HTMLやXML文書を操作するための基盤が作られます。
5$dom = new DOMDocument();
6
7// HTML文字列をDOMに読み込みます。
8// LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD フラグは、不必要なbodyやhtmlタグの自動挿入を防ぎ、
9// より制御されたDOM構造を生成するのに役立ちます。
10$dom->loadHTML('
11<!DOCTYPE html>
12<html>
13<head>
14    <title>DOMElement::replaceWith 例</title>
15</head>
16<body>
17    <h1>DOMElement::replaceWith メソッドの使用例</h1>
18    <p id="original-paragraph">このパラグラフが新しい要素に置き換えられます。</p>
19    <p>これは置き換えられない、別のパラグラフです。</p>
20</body>
21</html>
22', LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
23
24// IDが "original-paragraph" の要素（<p>タグ）を取得します。
25// これが `replaceWith` メソッドの対象となる要素です。
26$targetElement = $dom->getElementById('original-paragraph');
27
28// ターゲット要素が正常に取得できたかを確認します。
29if ($targetElement) {
30    // 新しい要素として `<span>` タグを作成します。
31    // 最初の引数はタグ名、2番目の引数はその要素のテキストコンテンツです。
32    $newElement = $dom->createElement('span', '元のパラグラフは新しいスパンタグに置き換えられました！');
33    
34    // 新しい要素にスタイル属性を追加して、視覚的に目立つようにします。
35    $newElement->setAttribute('style', 'color: blue; font-weight: bold;');
36
37    // `replaceWith` メソッドを呼び出して、元の `$targetElement` を `$newElement` で置き換えます。
38    // このメソッドは、元の要素をDOMツリーから削除し、その場所に新しい要素を挿入します。
39    // 引数には、`DOMNode` オブジェクトまたは文字列を1つ以上指定できます。
40    $targetElement->replaceWith($newElement);
41
42    // DOMの変更内容をHTML形式で出力します。
43    // `formatOutput` を `true` に設定すると、出力されるHTMLが整形され、読みやすくなります。
44    $dom->formatOutput = true;
45    echo $dom->saveHTML();
46} else {
47    // ターゲット要素が見つからなかった場合のメッセージを表示します。
48    echo "エラー: 置き換え対象の要素が見つかりませんでした。\n";
49}
50
51?>

PHPのDOMElement::replaceWithメソッドは、HTMLやXMLドキュメント内で既存の要素を別の要素やテキストで置き換える際に利用されます。このサンプルコードでは、まずDOMDocumentオブジェクトを初期化し、HTML文字列を読み込んで操作可能な状態にします。

次に、getElementByIdメソッドを使用して、IDが"original-paragraph"の特定の<p>タグを取得します。これがreplaceWithメソッドの対象となる要素です。その後、createElementメソッドで新しい<span>タグを作成し、その内容とスタイルを設定します。

取得した対象要素に対してreplaceWithメソッドを呼び出すことで、元の<p>タグは作成した新しい<span>タグによって置き換えられます。このメソッドは、元の要素をDOMツリーから削除し、その元の位置に引数で指定された新しいノードや文字列を挿入します。引数には、DOMNodeオブジェクトまたは文字列を一つ以上指定でき、複数の要素を挿入することも可能です。このメソッドは直接値を返しません（戻り値はvoidです）。

最終的に、変更が適用されたDOMツリー全体がHTML形式で出力され、元のパラグラフが新しいスパンタグに置き換わっていることを確認できます。これにより、ウェブコンテンツの動的な更新などをPHPで行うことが可能になります。

DOMElement::replaceWithメソッドをご利用の際、いくつかの注意点と補足事項があります。

まず、置き換え対象の要素がDOMツリー内に確実に存在するかを、必ず確認してください。サンプルコードのようにif ($targetElement)でnullチェックを行うことで、対象が見つからない場合のエラー発生を防ぎ、安全にコードを実行できます。

次に、このメソッドは引数としてDOMNodeオブジェクトだけでなく、HTML文字列も受け取ることが可能です。さらに、複数の引数を指定することで、一つの要素を複数の新しい要素やテキストで置き換えるといった柔軟な操作も行えます。

メソッドの戻り値はvoid、つまり何も返しません。そのため、replaceWithの実行結果を変数に代入しようとしても意味がない点にご留意ください。

また、replaceWithが実行されると、元の要素はDOMツリーから完全に削除されます。元の要素がそれ以降の処理で不要であることを確認してからメソッドを使用してください。HTML文字列で置き換える場合は、その文字列が正しいHTML断片であることを確認すると、予期せぬDOM構造の破損を防げます。