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

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

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

基本的な使い方

replaceChildメソッドは、あるノードが持つ子ノードの中から特定の子ノードを、別の新しいノードに置き換える処理を実行するメソッドです。このメソッドは親クラスであるDom\Nodeから継承されており、第1引数に新しいノードを、第2引数に置き換え対象となる既存の子ノードを指定します。処理が正常に完了した場合、メソッドは置き換えられて削除された古いノードを返します。何らかの理由で処理に失敗した場合は、falseを返します。ただし、Dom\Entityクラスのインスタンスは、XML文書のDTDで定義されたエンティティを表し、その性質上、読み取り専用として扱われます。そのため、Dom\Entityオブジェクトに対してreplaceChildメソッドを呼び出してDOMツリーの構造を変更しようとすると、変更が許可されていないことを示すDOMExceptionがスローされます。この例外は、読み取り専用のノードを変更しようとした場合に発生します。したがって、このメソッドはDom\Entityクラスに定義されていますが、クラスの特性により、実際に子ノードを置き換える操作には使用できない点に注意が必要です。

構文(syntax)


1$replacedChildOrFalse = $domEntity->replaceChild($newNode, $oldNode);

引数(parameters)

Dom\Node $node, Dom\Node $child

Dom\Node $node: 置換先の新しい子ノードを指定します。
Dom\Node $child: 削除して置換される現在の子ノードを指定します。

戻り値(return)

Dom\Node|false

指定されたノードを、子ノードリスト内の既存の子ノードの代わりに挿入します。置換が成功した場合は、削除された古い子ノードが返されます。置換が失敗した場合は、falseが返されます。

サンプルコード

PHP DOMDocument replaceChildで要素を置き換える


1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOM要素を新しい要素で置き換えるサンプルコード
7 */
8function replaceDomElementExample(): void
9{
10    // 操作対象のHTML文字列を定義
11    $htmlString = <<<HTML
12    <!DOCTYPE html>
13    <html lang="ja">
14    <head>
15        <meta charset="UTF-8">
16        <title>DOM操作の例</title>
17    </head>
18    <body>
19        <h1>元の見出し</h1>
20        <p id="target">この段落が置き換えられます。</p>
21        <ul>
22            <li>リスト項目1</li>
23        </ul>
24    </body>
25    </html>
26    HTML;
27
28    // DOMDocumentオブジェクトを作成し、HTMLを読み込む
29    $dom = new DOMDocument();
30    // HTML5の要素を正しく解釈し、エラー出力を抑制
31    libxml_use_internal_errors(true);
32    $dom->loadHTML($htmlString, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
33    libxml_clear_errors();
34
35    // 置き換える対象の要素(古いノード)をIDで取得
36    $oldChild = $dom->getElementById('target');
37
38    // oldChildが見つかった場合のみ処理を実行
39    if ($oldChild instanceof DOMNode) {
40        // 新しい要素(h2)を作成
41        $newChild = $dom->createElement('h2', 'これは新しい見出しです。');
42
43        // 親ノードを取得し、replaceChildメソッドを実行
44        // 第一引数: 新しいノード
45        // 第二引数: 置き換える古いノード
46        // 戻り値: 置き換えられて削除された古いノード
47        $replacedNode = $oldChild->parentNode->replaceChild($newChild, $oldChild);
48
49        // 置き換えが成功したか確認 (デバッグ用)
50        if ($replacedNode) {
51            // echo "置き換え成功: " . $replacedNode->nodeName . PHP_EOL;
52        }
53    }
54
55    // 結果を整形してHTMLとして出力
56    $dom->formatOutput = true;
57    echo $dom->saveHTML();
58}
59
60// 関数を実行
61replaceDomElementExample();
62

このサンプルコードは、PHPのDOM拡張機能を利用して、HTMLドキュメント内のある要素を別の新しい要素で置き換える方法を示しています。まずDOMDocumentオブジェクトを生成し、操作対象のHTMLを読み込みます。次にgetElementByIdメソッドで、置き換えたいid="target"を持つp要素を取得します。同時にcreateElementメソッドで、新しく挿入するためのh2要素を生成しておきます。

要素の置き換えにはreplaceChildメソッドを使用します。このメソッドは、置き換えたい要素の親ノード（$oldChild->parentNode）に対して実行する必要があります。第一引数には新しいノード、第二引数には置き換える対象の既存の子ノードを指定します。実行すると、第二引数で指定した要素がDOMツリーから削除され、その位置に第一引数の要素が挿入されます。replaceChildメソッドの戻り値は、置き換えによって削除された元のノードです。処理が失敗した場合はfalseが返るため、成功したかどうかの判定に利用できます。最後にsaveHTMLメソッドで、変更が反映されたHTML全体を出力しています。

getElementByIdメソッドは、HTML文書に有効なDTD（文書型定義）がないと期待通りに動作しないことがあります。より確実に対象要素を取得するにはDOMXPathの利用を推奨します。replaceChildメソッドの引数は、第一引数が「新しいノード」、第二引数が「置き換え対象の古いノード」です。この順番を間違えないよう注意してください。また、追加する新しいノードは、必ず置き換え先のDOMDocumentオブジェクト内で作成する必要があります。対象ノードが見つからない場合にエラーとなるため、サンプルコードのように事前に存在確認を行うことが安全な実装の基本です。戻り値は追加されたノードではなく、取り除かれた古いノードである点も重要です。

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


1<?php
2
3declare(strict_types=1);
4
5use DOMDocument;
6
7/**
8 * DOMDocumentのreplaceChildメソッドの使用例を示すクラス。
9 * この例では、HTMLドキュメント内のある要素を別の新しい要素に置き換えます。
10 */
11class DomReplaceChildExample
12{
13    /**
14     * サンプルコードを実行し、結果のHTMLを返します。
15     *
16     * @return string 置換処理後のHTML文字列
17     */
18    public static function run(): string
19    {
20        // 1. 操作対象のHTML文字列を定義します。
21        $html = '
22            <div id="container">
23                <h1>ドキュメントのタイトル</h1>
24                <p id="old-paragraph">これは置き換えられる古い段落です。</p>
25                <p>これはそのままの段落です。</p>
26            </div>
27        ';
28
29        // 2. DOMDocumentオブジェクトを生成し、HTMLを読み込みます。
30        $dom = new DOMDocument();
31        // HTMLの断片として扱うためのオプションを指定します。
32        // これにより、<html>や<body>タグが自動的に追加されるのを防ぎます。
33        $options = LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD;
34        $dom->loadHTML($html, $options);
35
36        // 3. 置換対象の古いノード（id="old-paragraph" の p 要素）を取得します。
37        $oldChild = $dom->getElementById('old-paragraph');
38
39        // 4. 置換するための新しいノード（div 要素）を作成します。
40        $newChild = $dom->createElement('div', 'これは新しく挿入されたブロックです。');
41        $newChild->setAttribute('class', 'new-content');
42
43        // 5. 親ノードを取得し、replaceChildメソッドを実行します。
44        // $oldChild->parentNode は、親である <div id="container"> を指します。
45        // replaceChild($newChild, $oldChild) は、$oldChild を $newChild で置き換えます。
46        // 戻り値は、削除されたノード（$oldChild）です。
47        if ($oldChild && $oldChild->parentNode) {
48            $removedNode = $oldChild->parentNode->replaceChild($newChild, $oldChild);
49        }
50
51        // 6. 変更後のDOMツリーをHTML文字列として出力します。
52        return $dom->saveHTML();
53    }
54}
55
56// クラスのメソッドを実行し、結果を出力します。
57echo DomReplaceChildExample::run();
58

このPHPコードは、DOMDocumentクラスを利用してHTML文書内のある要素を別の要素に置き換える処理を示しています。replaceChildメソッドは、特定の親要素が持つ子要素（子ノード）を、新しく作成した要素（ノード）で入れ替えるために使われます。

サンプルコードでは、まず操作対象のHTML文字列からDOMDocumentオブジェクトを生成します。次に、置き換え対象であるid="old-paragraph"の<p>要素と、新しく挿入するための<div>要素をそれぞれ準備します。

replaceChildメソッドは、親ノード->replaceChild(新しいノード, 古いノード)という形で呼び出します。第1引数には新しく挿入するノードを、第2引数には置き換え対象となる既存の子ノードを指定します。この例では、<p>要素の親である<div id="container">からこのメソッドを呼び出し、<p>要素を新しい<div>要素で置き換えています。

メソッドが成功すると、戻り値として置き換えられて削除されたノード（この場合は元の<p>要素）が返されます。失敗した場合はfalseが返ります。最後にsaveHTMLメソッドで変更後のHTMLを出力し、要素が正しく置き換えられたことを確認できます。

replaceChildメソッドで注意すべき点は引数の順序です。第一引数に「新しいノード」、第二引数に「置き換えたい古いノード」の順で指定します。処理を安全に行うため、サンプルコードのように、置換対象のノードやその親ノードが実際に存在するかをif文で必ず確認してください。対象が見つからない場合に処理を進めるとエラーの原因となります。また、createElementで作成する新しいノードは、必ず操作対象と同じDOMDocumentオブジェクトから生成する必要があります。loadHTMLのオプションは、HTMLの断片を扱う際に<html>や<body>タグが自動で追加されるのを防ぎ、意図しない構造になるのを避けるために有効です。