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

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

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

基本的な使い方

replaceWithメソッドは、DOMCharacterDataオブジェクトである呼び出し元のノード自身を、指定された新しいノードまたは文字列の集合で置き換えるメソッドです。DOMCharacterDataクラスは、XMLやHTMLドキュメント内のテキストデータ、コメント、CDATAセクションといった文字情報を保持するノードの基底クラスとして機能します。

このメソッドを利用すると、既存のノードを削除し、その場所に一つまたは複数の新しいコンテンツを簡潔に挿入できます。具体的には、replaceWithメソッドが呼び出されたノードは、まずその親ノードから削除されます。その後、メソッドの引数として渡されたすべてのノードや文字列が、削除されたノードが元々あった位置に、指定された順序で挿入されます。引数には、複数のDOMNodeオブジェクトを指定したり、複数の文字列を指定したり、これらを混在させて指定することが可能です。文字列が引数として渡された場合、それらは自動的にDOMTextノードに変換されてから挿入されます。

システムエンジニアを目指す初心者の方にとっては、WebページやXMLデータの構造を動的に変更する際に、非常に強力で直感的な手段を提供します。例えば、既存のテキストコンテンツを別のテキストや複雑なHTML要素に一度に置き換えたい場合に役立ちます。ただし、このメソッドを呼び出すノードは、必ず親ノードを持っている必要があります。親ノードを持たない「孤立した」ノードに対してreplaceWithメソッドを使用しようとすると、実行時にエラーが発生しますのでご注意ください。この機能はPHP 8で新たに導入されました。

構文(syntax)


1<?php
2// DOMDocument を作成し、サンプルHTMLをロードします。
3$dom = new DOMDocument();
4$dom->loadHTML('<div>既存の文字データ</div>');
5
6// <div>要素の子ノードである DOMText (DOMCharacterData を継承) を取得します。
7$characterDataNode = $dom->getElementsByTagName('div')->item(0)->firstChild;
8
9// replaceWith() メソッドを使用して、現在の文字データノードを新しいノード群で置き換えます。
10// 引数には DOMNode オブジェクトや文字列を複数指定できます。
11$characterDataNode->replaceWith('新しいデータ', $dom->createTextNode('の一部'));
12?>

引数(parameters)

DOMNode|string ...$nodes

DOMNode|string ...$nodes: 置換する新しいノード、またはノードに変換される文字列。可変長引数で、複数のノードまたは文字列を指定できます。

戻り値(return)

void

このメソッドは、呼び出したノードを新しいノードのセットに置き換えます。実行後、元のノードはDOMツリーから削除されます。戻り値はありません。

サンプルコード

PHP DOM replaceWithでノードを置き換える


1<?php
2
3/**
4 * DOMCharacterData::replaceWith メソッドの使用例を示します。
5 * この関数は、HTMLドキュメント内の既存のテキストノード（DOMCharacterDataのサブクラス）を、
6 * 新しいテキストとDOM要素の組み合わせに置き換える方法をデモンストレーションします。
7 *
8 * @return void
9 */
10function replaceCharacterDataExample(): void
11{
12    // 1. DOMDocument オブジェクトを作成します。
13    $dom = new DOMDocument();
14
15    // 2. HTMLコンテンツをロードします。
16    // loadHTML() で発生する可能性のある警告を抑制し、後で元に戻します。
17    libxml_use_internal_errors(true);
18    $html = '<!DOCTYPE html><html><body><p>これは元のテキストです。</p></body></html>';
19    $dom->loadHTML($html);
20    libxml_use_internal_errors(false); // エラーハンドリングを元に戻します
21
22    echo "--- 変換前のHTML ---\n";
23    // saveHTML() を使用して、現在のDOMツリーのHTML表現を出力します。
24    echo $dom->saveHTML() . "\n\n";
25
26    // 3. 置き換え対象となる DOMCharacterData ノードを見つけます。
27    // ここでは、最初の <p> タグの最初の子ノード（通常はテキストノード）を対象とします。
28    $paragraphs = $dom->getElementsByTagName('p');
29    if ($paragraphs->length > 0) {
30        $paragraph = $paragraphs->item(0); // 最初の <p> 要素を取得します
31
32        // <p>要素の最初の子ノードが DOMCharacterData (例: テキストノード) であることを確認します。
33        if ($paragraph->firstChild instanceof DOMCharacterData) {
34            $originalCharacterDataNode = $paragraph->firstChild; // 置き換え対象のノード
35
36            // 4. replaceWith() メソッドを使ってノードを新しい内容に置き換えます。
37            // replaceWith() は可変長引数を受け取り、DOMNode オブジェクトや文字列を複数指定できます。
38            // ここでは、新しいテキストノード、<strong>要素、別のテキストノードの順で置き換えます。
39            $newNodePart1 = $dom->createTextNode('新しい');
40            $strongNode = $dom->createElement('strong', '強調された');
41            $newNodePart2 = $dom->createTextNode('テキストです。');
42
43            // 既存のテキストノードを、これらの新しい複数のノードに置き換えます。
44            $originalCharacterDataNode->replaceWith($newNodePart1, $strongNode, $newNodePart2);
45
46            echo "--- 変換後のHTML ---\n";
47            echo $dom->saveHTML() . "\n";
48        } else {
49            echo "エラー: <p>要素の最初の子ノードが DOMCharacterData ではありません。\n";
50        }
51    } else {
52        echo "エラー: <p>要素が見つかりませんでした。\n";
53    }
54}
55
56// 関数を実行してデモンストレーションを開始します。
57replaceCharacterDataExample();
58

DOMCharacterData::replaceWith メソッドは、PHPでHTMLやXMLドキュメント内の文字データノードを新しい内容に置き換える際に使用されます。DOMCharacterDataは、テキストノードやコメントノードといった、ドキュメント内の文字情報を保持するノードの基底クラスです。

このメソッドを呼び出すと、呼び出し元である既存のDOMCharacterDataノードは、引数として渡された一つまたは複数のDOMNodeオブジェクトや文字列によって完全に置き換えられます。複数の引数を指定することで、既存のノードを複数の新しいノードやテキストの並びに置き換えることが可能です。このメソッドはvoidを返すため、処理が完了しても特に値を返しません。

サンプルコードでは、DOMDocumentに「これは元のテキストです。」というテキストを含むHTMLを読み込み、最初の<p>タグ内のテキストノードを見つけ出します。このテキストノードはDOMCharacterDataのインスタンスです。その後、replaceWithメソッドを使い、元のテキストノードを「新しい」というテキストノード、<strong>タグで囲まれた「強調された」という要素、そして「テキストです。」という別のテキストノードの３つの新しい内容に置き換えています。これにより、元々のシンプルなテキストが、複数の要素で構成される新しいコンテンツに更新される様子が確認できます。

DOMCharacterData::replaceWithメソッドは、テキストノードのようなDOMCharacterData型のノードを新しいノード群に置き換える際に使用します。他の種類のノードを操作する場合は、別のメソッドを検討してください。このメソッドは可変長引数を受け入れるため、既存の単一ノードを複数のDOMNodeオブジェクトや文字列に一度に置き換えられます。文字列はテキストノードとして挿入されます。新しい要素やテキストを挿入する際は、DOMDocument::createElement()やDOMDocument::createTextNode()でノードを事前に作成し渡すのが安全です。replaceWithはvoidを返すため、処理の成功・失敗を戻り値で直接確認できません。ノードの存在や型を事前に確認し、DOMDocument::loadHTML()で発生する可能性のある警告はlibxml_use_internal_errorsで適切にハンドリングするなど、堅牢なコードを心がけましょう。