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

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

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

基本的な使い方

replaceChildメソッドは、DOMツリーの構造を変更するために、指定された既存の子ノードを新しいノードで置き換える操作を実行するメソッドです。このメソッドは、PHPのDOM拡張機能において、ノードの追加、削除、変更といった基本的なDOM操作の一部を担い、文書の動的な構築や更新に不可欠な機能を提供します。

Dom\Textクラスは、すべてのDOMノードの共通の基底クラスであるDom\Nodeクラスを継承しており、そのためreplaceChildメソッドもDom\Textオブジェクトから利用可能であるかのように見えます。しかし、Dom\Textノードは、その本質的な性質として、テキストデータのみを保持し、他のノードを子として持つことができません。

このため、Dom\Textオブジェクトに対してreplaceChildメソッドを呼び出すと、たとえ引数を正しく渡したとしても、常にエラー（DOM_NO_MODIFICATION_ALLOWED_ERR）が発生します。これは、Dom\Textノードが、子ノードを内包するコンテナとしての役割を持たないことに起因します。

通常、replaceChildメソッドは、Dom\Elementなどの子ノードを持つことができる親ノードが、自身の子ノードを別のノードと交換する際に用いられます。メソッドの引数には、新しく追加したいノードと、置き換えの対象となる既存の子ノードを指定します。成功した場合、メソッドは置き換えられた既存の子ノードを返します。Dom\Textクラスにこのメソッドが存在するのは、クラス継承の仕組みによるものですが、実際にはその機能を利用できないという点を、システムエンジニアを目指す上では理解しておくことが重要です。

構文(syntax)


1$textNode->replaceChild(Dom\Node $newChild, Dom\Node $oldChild): Dom\Node;

引数(parameters)

Dom\Node $node, Dom\Node $child

Dom\Node $node: 置き換える対象となる子ノード
Dom\Node $child: 新しく挿入する子ノード

戻り値(return)

Dom\Node

指定されたノードを、現在のノードの子ノードとして置き換えます。置き換えられた古い子ノードを返します。

サンプルコード

PHP DOM: replaceChildで子ノードを置き換える


1<?php
2
3/**
4 * Dom\Node::replaceChild() メソッドの使用例。
5 *
6 * この関数は、親ノードの子ノードを新しいノードで置き換える方法を示します。
7 * Dom\Text クラスは Dom\Node を継承しており、replaceChild メソッドは Dom\Node に定義されています。
8 * ただし、Dom\Text ノード自体は子ノードを持たないため、通常は親要素ノード (例: Dom\Element)
9 * に対してこのメソッドを呼び出し、その子ノードを置き換えます。
10 */
11function exampleReplaceChildNode(): void
12{
13    // 1. 新しい Dom\Document を作成します。
14    $document = new Dom\Document('1.0', 'UTF-8');
15    $document->formatOutput = true; // 出力を見やすくフォーマットします
16
17    // 2. ルート要素 (例: <body>) を作成し、ドキュメントに追加します。
18    $body = $document->createElement('body');
19    $document->appendChild($body);
20
21    // 3. 既存の Dom\Element を作成し、body 要素に追加します。
22    $paragraph = $document->createElement('p');
23    $body->appendChild($paragraph);
24
25    // 4. 置き換えの対象となる Dom\Text ノードを作成し、paragraph に子として追加します。
26    $originalText = $document->createTextNode('これは元のテキストです。');
27    $paragraph->appendChild($originalText);
28
29    echo "--- 置き換え前ドキュメント ---\n";
30    echo $document->saveHTML();
31    echo "\n";
32
33    // 5. 新しい Dom\Text ノードを作成します。
34    $newText = $document->createTextNode('これは新しいテキストに置き換えられました！');
35
36    // 6. Dom\Element ($paragraph) に対して replaceChild() を呼び出し、
37    //    $originalText を $newText で置き換えます。
38    //    第一引数は新しいノード、第二引数は置き換える既存の子ノードです。
39    //    メソッドは置き換えられた古いノード ($originalText) を返します。
40    $replacedOldNode = $paragraph->replaceChild($newText, $originalText);
41
42    echo "--- 置き換え後ドキュメント ---\n";
43    echo $document->saveHTML();
44    echo "\n";
45
46    // 置き換えられたノードが期待通りであるか確認できます。
47    if ($replacedOldNode === $originalText) {
48        echo "成功: 元のテキストノードが正しく新しいテキストノードに置き換えられました。\n";
49    } else {
50        echo "エラー: 置き換えられたノードが期待と異なります。\n";
51    }
52}
53
54// 関数を実行します。
55exampleReplaceChildNode();

PHPのDom\Node::replaceChildメソッドは、DOM (Document Object Model) ツリーにおいて、指定した親ノードの既存の子ノードを新しいノードで置き換える際に使用される重要な機能です。このメソッドはDom\Nodeクラスに定義されており、通常はDom\Elementのような子ノードを持てる要素に対して呼び出されます。リファレンスにはDom\Textクラスのメソッドとして記載されていますが、Dom\Textノード自体は子ノードを持たないため、実際にはその親要素からこのメソッドを利用して、テキストノードを置き換えることになります。

第一引数には、既存の子ノードと入れ替える「新しいDom\Nodeオブジェクト」を指定します。第二引数には、置き換えの対象となる「既存のDom\Nodeの子オブジェクト」を指定します。このメソッドが成功すると、DOMツリーから削除され置き換えられた「古いDom\Nodeオブジェクト」が戻り値として返されます。これにより、動的にWebページの内容を更新したり、XMLデータを操作したりする際に、効率的にノード構造を変更することが可能です。

このサンプルコードで示されるDom\Node::replaceChild() メソッドは、親のDom\Elementノードに対して呼び出されている点にご注意ください。Dom\Textクラスは子ノードを持たないため、Dom\Textノード自体にこのメソッドを適用しても機能しません。必ずその親要素（例: Dom\Element）から呼び出し、その子ノードを置き換えるようにしてください。

引数の順序も重要です。第一引数に「新しく挿入するノード」、第二引数に「置き換えたい既存の子ノード」を指定します。この順序を間違えると意図しない動作となります。また、置き換え対象の子ノードが、呼び出し元ノードの実際の子でない場合、エラーが発生する可能性があります。メソッドは置き換えられた古いノードを返しますので、処理の確認に活用できます。

PHP DOM replaceChild でテキストノードを置換する


1<?php
2
3/**
4 * Dom\Node::replaceChild メソッドの基本的な使用例。
5 *
6 * replaceChild メソッドは通常、親ノードがその子ノードを置き換えるために使用されます。
7 * Dom\Text ノードは Dom\Node を継承しているため、このメソッドは Dom\Text ノードの
8 * 親ノードによって、その Dom\Text ノードを別のノードで置き換える際に利用できます。
9 * Dom\Text ノード自体は子ノードを持てないため、自身が replaceChild を呼び出すことは
10 * 一般的な用途ではありません。
11 *
12 * この例では、既存のテキストノードを新しいテキストノードで置き換える方法を示します。
13 */
14function demonstrateDomTextReplaceChild(): void
15{
16    // 1. 新しい DOM Document を作成します。
17    // PHP 8 からは名前空間付きの DOM クラスを使用できます。
18    $dom = new DOM\Document();
19    $dom->formatOutput = true; // 出力を見やすくするための設定
20
21    // 2. ルート要素（例えば <body>）を作成し、Document に追加します。
22    $body = $dom->createElement('body');
23    $dom->appendChild($body);
24
25    // 3. ルート要素に既存の Dom\Text ノードを追加します。
26    $originalTextNode = $dom->createTextNode('これは元のテキストです。');
27    $body->appendChild($originalTextNode);
28
29    echo "--- 置換前の DOM 構造 ---\n";
30    echo $dom->saveHTML();
31    echo "\n";
32
33    // 4. 新しいノード（ここでは別の Dom\Text ノード）を作成します。
34    $newTextNode = $dom->createTextNode('これは新しいテキストです！');
35
36    // 5. 親ノード ($body) の replaceChild メソッドを使用して、
37    // 既存のテキストノード ($originalTextNode) を新しいテキストノード ($newTextNode) で置き換えます。
38    // replaceChild(新しいノード, 置き換えられる古いノード)
39    $replacedNode = $body->replaceChild($newTextNode, $originalTextNode);
40
41    echo "--- 置換後の DOM 構造 ---\n";
42    echo $dom->saveHTML();
43    echo "\n";
44
45    // replaceChild メソッドは置き換えられた古いノードを返します。
46    if ($replacedNode === $originalTextNode) {
47        echo "Dom\Text ノードは正常に置き換えられました。\n";
48    } else {
49        echo "Dom\Text ノードの置き換えに失敗しました。\n";
50    }
51}
52
53// 関数を実行して、Dom\Text ノードの置き換え処理を確認します。
54demonstrateDomTextReplaceChild();
55
56?>

PHP 8のDom\Text::replaceChildメソッドは、DOM（Document Object Model）ツリー内のノードを置き換える際に使用される機能です。Dom\TextクラスはDom\Nodeクラスを継承しているため、このメソッドを利用できますが、Dom\Textノード自体は子ノードを持てません。したがって、このメソッドは通常、Dom\Textノードを子に持つ親ノードが、その子であるDom\Textノードを別のノードに置き換える目的で呼び出します。

このメソッドは、既存の子ノードを指定した新しいノードで完全に置き換える役割を果たします。第一引数Dom\Node $nodeには、新しく追加したいノードオブジェクトを指定し、第二引数Dom\Node $childには、DOMツリーから削除され、置き換えられる既存のノードオブジェクトを指定します。この$childは、メソッドを呼び出す親ノードの実際の子である必要があります。メソッドの実行後、DOMツリーからは$childが削除され、その代わりに$nodeが同じ位置に挿入されます。

戻り値はDom\Node型で、DOMツリーから削除された古いノード、つまり$childとして渡したノードオブジェクトが返されます。これにより、置き換えられたノードに対してさらに操作を行ったり、内容を確認したりすることが可能です。

提示されたサンプルコードでは、まず<body>要素の中に「これは元のテキストです。」というテキストノードを追加します。その後、<body>のreplaceChildメソッドを使い、「これは元のテキストです。」ノードを「これは新しいテキストです！」という新しいテキストノードで置き換えることで、DOMツリーの動的な変更方法を示しています。この機能は、ウェブページのコンテンツをプログラムで変更する際に非常に役立ちます。

このサンプルコードのreplaceChildメソッドは、子ノードを持つ要素（親ノード）がその子ノードを置き換えるために使用するものです。Dom\Textノード自体は子ノードを持たないため、自身が直接このメソッドを呼び出すことは一般的ではありません。

特に注意が必要なのは引数の順番で、replaceChild(新しいノード, 置き換えられる古いノード)という順序で指定します。これを間違えると意図しない挙動やエラーの原因となりますので、常に新しいノードを第一引数、置き換えたい既存のノードを第二引数に指定してください。また、このメソッドは置き換えられた「古いノード」を戻り値として返します。これは、置き換えが成功したことを確認する際に役立ちます。PHP 8からはDOMクラスが名前空間に対応し、DOM\Documentのように記述できます。