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

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

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

基本的な使い方

replaceWithメソッドは、Dom\HTMLElementクラスに属し、現在のHTML要素を新しいノードまたは複数のノードに置き換えることを実行するメソッドです。このメソッドは、呼び出し元のDom\HTMLElementオブジェクトが表現するHTML要素をDOM（Document Object Model）ツリーから削除し、その代わりに引数として渡されたノード群を元の位置に挿入します。これにより、ウェブページの特定のコンテンツを動的に完全に変更することが可能になります。

引数には、Dom\Nodeオブジェクト（例えば、別のHTML要素やテキストノードなど）を複数、または複数の文字列を指定できます。特に重要な点として、文字列が渡された場合、それらはHTMLとして解析されずに純粋なテキストノードとして扱われます。したがって、HTMLタグを含む文字列を要素として挿入したい場合は、事前に別の方法でHTMLをパースしてDom\Nodeオブジェクトとして渡す必要があります。

例えば、特定の段落要素（<p>）を、新しい<div>要素や単なるテキストで置き換えたい場合にこのメソッドを利用します。元の要素はDOMツリーから完全に削除されるため、ウェブページ上から消滅し、置き換えられた新しい内容がその位置に表示されます。このメソッドは値を返しません。ウェブページ上で要素の内容や構造を柔軟に操作する際に非常に便利な機能です。

構文(syntax)


1<?php
2
3$domHTMLElementInstance->replaceWith($domNodeInstance, 'text string', $anotherDomNodeInstance);

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string ...$nodes: 置換するDom\Nodeオブジェクト、またはHTML文字列を可変長引数で指定します。

戻り値(return)

void

このメソッドは、要素を他の要素で置き換える操作を行います。具体的には、指定されたノードまたはノードの配列で、この要素を置き換えます。このメソッドは何も値を返しません。

サンプルコード

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


1<?php
2
3/**
4 * Dom\HTMLElement::replaceWith の使用例を示す関数
5 *
6 * 指定されたIDを持つHTML要素を、新しい要素やテキストで置き換えます。
7 */
8function demonstrateReplaceWith(): void
9{
10    // 操作対象となるHTML文字列を定義
11    $html = <<<HTML
12    <!DOCTYPE html>
13    <html lang="ja">
14    <head>
15        <meta charset="UTF-8">
16        <title>DOM replaceWith Example</title>
17    </head>
18    <body>
19        <h1>元のコンテンツ</h1>
20        <div id="content">
21            <p id="target">この段落が置き換えられます。</p>
22        </div>
23        <p>この段落は変更されません。</p>
24    </body>
25    </html>
26    HTML;
27
28    // DOMDocumentオブジェクトを作成し、HTMLを読み込む
29    $dom = new DOMDocument();
30    // HTML5のタグ等で発生する警告を抑制するため、libxmlのエラーハンドリングを制御
31    libxml_use_internal_errors(true);
32    $dom->loadHTML($html);
33    libxml_clear_errors();
34
35    // id="target" を持つ要素を取得 (これは Dom\HTMLElement のインスタンス)
36    $targetElement = $dom->getElementById('target');
37
38    // 要素が見つかった場合のみ処理を実行
39    if ($targetElement) {
40        // 新しい要素を作成
41        $newHeading = $dom->createElement('h2', 'これは新しい見出しです');
42        $newParagraph = $dom->createElement('p', 'これは新しい段落です。');
43
44        // replaceWith()メソッドを使い、対象要素を複数の新しいノードや文字列で置き換える
45        // 引数には Dom\Node オブジェクトや文字列を可変長で渡すことができます。
46        $targetElement->replaceWith(
47            $newHeading,
48            '文字列ノードも直接挿入できます。',
49            $newParagraph
50        );
51    }
52
53    // 変更後のHTMLを出力（文字化けを防ぐためヘッダーを指定）
54    header('Content-Type: text/plain; charset=utf-8');
55    echo $dom->saveHTML();
56}
57
58demonstrateReplaceWith();

Dom\HTMLElement::replaceWithメソッドは、特定のHTML要素を、一つまたは複数の新しい要素やテキストで置き換えるための機能です。このメソッドは、呼び出し元の要素をDOMツリーから削除し、引数で指定されたノードをその場所に挿入します。

サンプルコードでは、まずDOMDocumentオブジェクトを生成してHTML文字列を読み込みます。次にgetElementByIdメソッドを使い、置き換えの対象となるid="target"を持つp要素を取得します。その後、置き換え後に追加したいh2要素とp要素をcreateElementで新しく作成します。

中心となるreplaceWithメソッドの呼び出しでは、取得した対象要素に対して、新しく作成したh2要素、文字列、そして新しいp要素の3つを引数として渡しています。このメソッドの引数には、Dom\Nodeオブジェクトや文字列を複数指定することができ、指定した順番で元の要素の位置に挿入されます。このメソッドはDOM構造を直接変更するだけで、処理結果として値を返さないため、戻り値はvoidとなります。

最後にsaveHTMLメソッドで変更後のHTMLを出力すると、元のp要素があった場所に、新しい見出し、テキスト、段落が挿入されていることを確認できます。

replaceWithメソッドは、呼び出し元の要素をDOMツリーから削除し、引数で指定した新しいノードや文字列に置き換えます。この操作の後は、元の要素の変数を参照しても意図通りに動作しないため注意が必要です。引数にはcreateElementで作成した要素だけでなく、通常の文字列も直接渡せます。文字列は自動的にテキストノードとして扱われ、複数の要素や文字列をカンマ区切りで同時に指定することも可能です。また、getElementByIdで要素を取得するには、読み込むHTMLに<!DOCTYPE>宣言が必須である点も覚えておきましょう。宣言がないと要素が見つからず、処理が実行されません。