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

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

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

基本的な使い方

replaceChildメソッドは、DOMEntityノードの子ノードを新しいノードで置き換えるメソッドです。DOMEntityは、XML文書におけるエンティティを表現するクラスであり、replaceChildメソッドはそのエンティティノードの構造を操作するために使用されます。

このメソッドは、置き換える既存の子ノードと、新しく挿入するノードの2つの引数を取ります。メソッドの呼び出しにより、既存の子ノードはDOMツリーから削除され、新しいノードが代わりに挿入されます。この操作は、エンティティノードの構造を動的に変更する必要がある場合に役立ちます。例えば、特定のエンティティ参照を別のエンティティ参照に置き換えたり、エンティティの内容を更新したりする際に利用できます。

replaceChildメソッドは、DOMEntityノードが読み取り専用である場合や、指定されたノードが適切なタイプでない場合など、いくつかの状況で例外をスローする可能性があります。したがって、このメソッドを使用する際には、DOM構造とノードの互換性を慎重に確認する必要があります。

具体的には、以下の手順でreplaceChildメソッドを使用します。

置き換えたい子ノードを特定します。
新しく挿入するノードを作成または取得します。
replaceChildメソッドを呼び出し、既存の子ノードと新しいノードを引数として渡します。

メソッドが正常に実行されると、DOMツリーが更新され、指定された子ノードが新しいノードで置き換えられます。このメソッドは、XML文書の構造をプログラム的に操作する上で重要な役割を果たします。

構文(syntax)


1DOMEntity::replaceChild(DOMNode $newChild, DOMNode $oldChild): DOMNode|false

引数(parameters)

DOMNode $newChild, DOMNode $oldChild

DOMNode $newChild: 新しく挿入する子ノードを指定します。
DOMNode $oldChild: 置換する既存の子ノードを指定します。

戻り値(return)

DOMNode|false

指定された要素ノードを、既存の子ノードと置き換えます。置き換えが成功した場合は、置き換えられた古い子ノードを返します。失敗した場合は false を返します。

サンプルコード

PHP DOMDocument replaceChildで子ノードを置換する


1<?php
2
3/**
4 * DOM要素の子ノードを置き換えるサンプルコード
5 *
6 * この関数は、指定されたXML文字列内の特定の要素を新しい要素に置き換えます。
7 * DOMDocumentを使用してXMLをパースし、replaceChildメソッドでノードを置換します。
8 */
9function replaceDomElementExample(): void
10{
11    // 操作対象のXML文字列
12    $xmlString = <<<XML
13<?xml version="1.0" encoding="UTF-8"?>
14<root>
15  <item>
16    <title>古いタイトル</title>
17    <author>著者A</author>
18  </item>
19</root>
20XML;
21
22    // DOMDocumentオブジェクトを作成
23    $dom = new DOMDocument();
24    $dom->formatOutput = true; // 出力するXMLを整形する
25    $dom->loadXML($xmlString);
26
27    // 親要素（<item>）を取得
28    $parent = $dom->getElementsByTagName('item')->item(0);
29
30    // 置き換えられる古い子要素（<title>）を取得
31    $oldChild = $dom->getElementsByTagName('title')->item(0);
32
33    // 新しく作成する子要素（<newTitle>）
34    $newChild = $dom->createElement('newTitle', '新しいタイトルに置換しました');
35
36    // 親要素（<item>）のreplaceChildメソッドを呼び出し、子要素を置き換える
37    if ($parent && $oldChild) {
38        $parent->replaceChild($newChild, $oldChild);
39    }
40
41    // 変更前と変更後のXMLを出力して確認
42    echo "--- 変更前 ---\n";
43    echo $xmlString . "\n\n";
44    echo "--- 変更後 ---\n";
45    echo $dom->saveXML();
46}
47
48// 関数を実行
49replaceDomElementExample();
50
51?>

このPHPサンプルコードは、DOMDocumentクラスを利用してXMLデータ内のある要素を別の新しい要素に置き換える方法を示しています。中心となるのはreplaceChildメソッドで、これは特定の親ノードが持つ子ノードを、指定した新しいノードで置き換える機能を提供します。

このメソッドの第1引数には、新しく挿入するDOMNodeオブジェクト（サンプルコードの$newChild）を指定します。第2引数には、置き換えの対象となる既存の子ノード（$oldChild）を指定します。サンプルコードでは、<item>という親要素の持つ<title>という子要素を、新しく作成した<newTitle>要素に置き換えています。

処理が成功した場合、replaceChildメソッドは置き換えられて削除された古いノード（$oldChild）を返します。もし、指定した古いノードがその親要素の子でなかった場合など、処理に失敗した際にはfalseが返されます。これにより、処理が正しく行われたかを確認できます。

replaceChildメソッドは、置き換えたい子ノードの親ノードから呼び出す必要があります。サンプルコードでは親要素である$parentが該当します。getElementsByTagNameは要素が見つからない場合にnullを返すため、メソッド呼び出しの前にif文で親ノードと置き換え対象の子ノードがnullでないことを確認するのは、エラーを防ぐための重要な処理です。また、createElementで作成する新しいノードは、操作しているDOMDocumentインスタンスに属している必要があります。このメソッドは成功すると置き換えられた古いノードを返し、失敗した場合はfalseを返すため、処理の成否を確認したい場合にこの戻り値を利用できます。

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


1<?php
2
3/**
4 * DOMNode::replaceChild を使用してHTML要素を置き換えるサンプル関数です。
5 *
6 * この例では、<p>要素を新しく作成した<span>要素に置き換えます。
7 * replaceChildメソッドは、DOMNodeインターフェイスで定義されており、
8 * DOMElementなど多くの子クラスで利用できます。
9 *
10 * @return void
11 */
12function replaceDomElementExample(): void
13{
14    // 操作対象のHTML文字列
15    $htmlString = '
16    <!DOCTYPE html>
17    <html>
18    <body>
19        <div id="container">
20            <p id="target">これは古いパラグラフです。</p>
21            <span>これは隣の要素です。</span>
22        </div>
23    </body>
24    </html>
25    ';
26
27    // 1. DOMDocumentオブジェクトを作成し、HTMLを読み込みます
28    $dom = new DOMDocument();
29    // HTML5の要素を正しく解釈するためにエラーを抑制します
30    libxml_use_internal_errors(true);
31    $dom->loadHTML($htmlString);
32    libxml_clear_errors();
33
34    // 2. 置換対象となる古いノード(p#target)を取得します
35    $oldChild = $dom->getElementById('target');
36    if ($oldChild === null) {
37        echo '置換対象の要素が見つかりませんでした。';
38        return;
39    }
40
41    // 3. 置換するための新しいノード(span要素)を作成します
42    $newChild = $dom->createElement('span', 'これは新しく置き換えられたテキストです。');
43    $newChild->setAttribute('class', 'highlight'); // 新しい要素に属性を追加
44
45    // 4. 親ノード上で、古いノードを新しいノードに置換します
46    // $oldChild->parentNode は div#container を指します
47    if ($oldChild->parentNode) {
48        // replaceChild は、取り除かれた古いノード ($oldChild) を返します
49        $removedNode = $oldChild->parentNode->replaceChild($newChild, $oldChild);
50    }
51
52    // 5. 変更後のHTML全体を出力して確認します
53    echo $dom->saveHTML();
54}
55
56// サンプル関数を実行します
57replaceDomElementExample();
58
59?>

PHPのDOMNode::replaceChildメソッドは、特定のHTML要素（ノード）の子要素を、別の新しい要素に置き換えるために使用します。ウェブページの特定の部分を動的に書き換えたい場合に役立ちます。

サンプルコードでは、まずDOMDocumentオブジェクトを使い、文字列で定義されたHTMLを解析・操作可能な状態にしています。次に、getElementByIdメソッドで置き換えの対象となる要素を取得し、これを古いノード$oldChildとして準備します。同時に、createElementメソッドで新しく挿入する要素を新しいノード$newChildとして作成しています。

replaceChildメソッドの重要な点は、置き換えたい要素の親ノード（この例では<div>要素）に対して実行する点です。メソッドの第1引数に新しいノード$newChildを、第2引数に置き換え対象の古いノード$oldChildを指定します。

処理が成功すると、このメソッドは戻り値として、取り除かれた古いノード（元の要素）を返します。もし置き換えに失敗した場合はfalseが返ります。このサンプルを実行すると、最終的に元の要素がクラス属性付きの新しい要素に置き換えられたHTMLが出力されます。

replaceChildメソッドを利用する際は、置き換えたい要素（古いノード）の親ノードから呼び出す必要があります。子ノード自身から呼び出すことはできませんので注意してください。また、getElementByIdなどで要素を取得する際、対象が存在しないとnullが返ります。サンプルコードのように事前にnullチェックを行うことで、エラーを未然に防ぐことができます。新しく作成するノードは、必ず操作中のDOMDocumentオブジェクトに属している必要があります。例えば$dom->createElement()のように、同じインスタンスから生成してください。libxml_use_internal_errors(true)はHTML5などの解釈で発生する警告を抑制し、プログラムを安定させるために有効な記述です。