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

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

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

基本的な使い方

replaceWithメソッドは、DOMツリー内の現在のテキストノードを、指定された一つまたは複数のノードに置き換えるためのメソッドです。

このメソッドは、Dom\Textクラスのインスタンス、つまりHTMLやXML文書における特定のテキスト部分に対して呼び出されます。主に、既存のテキストコンテンツを他の要素や新しいテキストで動的に変更したい場合に利用されます。

replaceWithメソッドが実行されると、まず呼び出し元のテキストノードがDOMツリーから完全に削除されます。その後、メソッドの引数として渡された新しいノード群が、削除されたテキストノードがあった正確な位置に順番に挿入されます。引数には、Dom\Nodeインターフェースを実装する任意のノード（例えば、新しいテキストノード、要素ノードなど）を複数指定することが可能です。

この機能により、例えば特定のテキストコンテンツを強調表示する要素（<strong>タグなど）に置き換えたり、古い情報を新しいテキストや複数の要素で構成される複雑な内容に更新したりすることができます。文書の構造を損なうことなく、コンテンツの柔軟な変更を実現するための強力なツールとなります。このメソッドは特に戻り値を持ちません。

構文(syntax)


1<?php
2// Dom\Text::replaceWith ( Dom\Node|string ...$nodes ) : void
3
4// Dom\Text クラスのインスタンスを仮定します（実際にはDOMツリーから取得されます）
5$domTextInstance = new DOMText('元のテキストコンテンツ');
6
7// 既存のテキストノードを新しい文字列で置き換える構文例
8$domTextInstance->replaceWith('新しいテキストコンテンツ');

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string ...$nodes: 置換するDOMノードまたは文字列を指定します。複数指定可能です。

戻り値(return)

void

このメソッドは、呼び出したDom\Textノードを、指定された新しいノードで置き換えます。戻り値はありません。

サンプルコード

PHP DOM Text::replaceWithでノードを置換する


1<?php
2
3// DOMDocumentのインスタンスを作成
4// HTML5互換モードでパーシングするため、loadHTMLではなくDOMHTMLDocumentを使用することも可能ですが、
5// ここでは一般的なDOMDocumentと基本的なHTML構造を使用します。
6$dom = new DOMDocument('1.0', 'UTF-8');
7$dom->formatOutput = true; // 出力されるHTMLを見やすく整形する設定
8
9// サンプルHTMLコンテンツをロード
10// replaceWithメソッドは既存のノードを置き換えるため、
11// あらかじめノードが存在するHTMLを準備します。
12$htmlContent = '
13<!DOCTYPE html>
14<html>
15<head>
16    <title>PHP Dom\\Text::replaceWith 例</title>
17</head>
18<body>
19    <div id="container">
20        <h1>これは元のテキストです。</h1>
21        <p>この段落の「重要な部分」を置き換えます。</p>
22    </div>
23</body>
24</html>';
25$dom->loadHTML($htmlContent);
26
27// 置き換えたいテキストノードを見つけるためにXPathを使用します。
28// ここでは、<p>要素内のテキストノードをターゲットとします。
29$xpath = new DOMXPath($dom);
30$paragraphElement = $xpath->query('//p')->item(0);
31
32if ($paragraphElement) {
33    // <p>要素内の最初のテキストノードを取得します。
34    // DOMTextクラスはDom\Textを継承しており、replaceWithメソッドが利用可能です。
35    $originalTextNode = $paragraphElement->firstChild;
36
37    if ($originalTextNode instanceof DOMText) {
38        // DOM操作前のHTMLを出力して確認
39        echo "--- DOM操作前のHTML ---\n";
40        echo $dom->saveHTML() . "\n\n";
41
42        // Dom\Text::replaceWithメソッドを使用して、既存のテキストノードを新しい文字列で置き換えます。
43        // 引数にはDom\Nodeオブジェクトまたは文字列を複数指定できます。
44        // この例では、元のテキストノード全体を「この段落の新しい内容です。」という文字列で置き換えます。
45        $originalTextNode->replaceWith('この段落の新しい内容です。');
46
47        // DOM操作後のHTMLを出力して確認
48        echo "--- DOM操作後のHTML ---\n";
49        echo $dom->saveHTML() . "\n";
50    } else {
51        echo "エラー: <p>要素内にテキストノードが見つかりませんでした。\n";
52    }
53} else {
54    echo "エラー: <p>要素が見つかりませんでした。\n";
55}
56
57?>

PHPのDom\Text::replaceWithメソッドは、HTMLやXMLドキュメント内の既存のテキストノードを、指定した新しいノードや文字列で置き換えるために使用されます。このメソッドは、ウェブページの内容を動的に変更したい場合に非常に便利です。

サンプルコードでは、まずDOMDocumentクラスでHTMLコンテンツを読み込み、操作の準備をしています。次に、DOMXPathを使って<p>要素内の最初のテキストノードを特定しています。この特定されたテキストノードはDOMTextクラスのインスタンスであり、Dom\Textクラスを継承しているためreplaceWithメソッドを利用できます。

replaceWithメソッドの引数には、新しい内容としてDom\Nodeオブジェクトや文字列を複数指定できます。これにより、元のテキストノードを新しい文字列だけでなく、例えば別のHTML要素に置き換えることも可能です。このメソッドの戻り値はvoid、つまり何も返しませんが、メソッドが実行されるとDOMツリーが直接更新され、元のテキストノードが指定された内容に置き換わります。

このサンプルでは、<p>要素内にあった「この段落の「重要な部分」を置き換えます。」というテキストノード全体を、$originalTextNode->replaceWith('この段落の新しい内容です。');というコードで「この段落の新しい内容です。」という文字列に置き換えています。これにより、DOM操作後のHTMLでは<p>タグ内のテキストが変更されていることが確認できます。このように、replaceWithメソッドは既存のテキストコンテンツを柔軟に更新する際に役立ちます。

Dom\Text::replaceWithメソッドは、テキストノードにのみ適用でき、要素ノードなどには利用できません。引数にはDOMノードオブジェクトや文字列を複数指定でき、これらが元のテキストノードを置き換え、元のノードは完全に削除されます。元の情報は失われるため、必要に応じて事前に保持してください。メソッドの戻り値はvoidで、成功を直接確認できないため、実行後のDOMツリーの状態を確認することが重要です。 HTML解析時、インデントや改行もテキストノードとして扱われる場合があるため、意図したテキストノードを正確に特定する必要があります。