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

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment の replaceChildren メソッドを使用して、
5 * すべての子ノードを削除するサンプルコード。
6 * replaceChildren は既存の子ノードを指定されたノードで置き換えますが、
7 * 引数なしで呼び出すことで、すべての子ノードを削除できます。
8 */
9function removeAllChildrenFromFragment(): void
10{
11    // DOM要素を作成するための Dom\Document インスタンスを準備
12    $dom = new Dom\Document();
13
14    // Dom\DocumentFragment インスタンスを作成
15    $fragment = new Dom\DocumentFragment();
16
17    // フラグメントに追加する子ノードを作成
18    // Dom\DocumentFragment は自身ではノードを作成できないため、Dom\Document を経由します
19    $paragraph1 = $dom->createElement('p', 'これは最初の子ノノードです。');
20    $span1 = $dom->createElement('span', 'これは2番目の子ノードです。');
21    $div1 = $dom->createElement('div', 'これは3番目の子ノードです。');
22
23    // 作成したノードをフラグメントに追加
24    $fragment->appendChild($paragraph1);
25    $fragment->appendChild($span1);
26    $fragment->appendChild($div1);
27
28    echo "--- replaceChildren() 実行前 ---\n";
29    echo "フラグメントの子ノード数: " . $fragment->childNodes->length . "\n";
30    echo "フラグメントの内容:\n";
31    // 現在の子ノードを列挙して表示
32    foreach ($fragment->childNodes as $node) {
33        echo "  - <" . $node->nodeName . "> " . $node->textContent . "\n";
34    }
35
36    // Dom\DocumentFragment::replaceChildren() を引数なしで呼び出し、
37    // すべての子ノードを削除します。
38    // これは既存の子ノードを空のリストで置き換えることを意味します。
39    $fragment->replaceChildren();
40
41    echo "\n--- replaceChildren() 実行後 ---\n";
42    echo "フラグメントの子ノード数: " . $fragment->childNodes->length . "\n";
43    echo "フラグメントの内容:\n";
44    // 削除後の子ノードを列挙して表示（空であることを確認）
45    if ($fragment->childNodes->length === 0) {
46        echo "  (子ノードはすべて削除されました。)\n";
47    } else {
48        foreach ($fragment->childNodes as $node) {
49            echo "  - <" . $node->nodeName . "> " . $node->textContent . "\n";
50        }
51    }
52}
53
54// 関数を実行
55removeAllChildrenFromFragment();
56

PHPのDom\DocumentFragment::replaceChildren()メソッドは、対象となるDom\DocumentFragmentインスタンスに現在存在するすべての子ノードを、指定された新しいノードのセットで置き換えるために使用されます。このメソッドは、HTMLやXMLの断片的なDOM構造を効率的に操作する際に非常に役立ちます。

引数にはDom\Nodeオブジェクト、または文字列を複数（...$nodes）指定できます。文字列が渡された場合、それは自動的にテキストノードとして扱われ、既存の子ノードと置き換えられます。

特に注目すべきは、このreplaceChildren()メソッドを引数なしで呼び出した場合です。この場合、既存のすべての子ノードが完全に削除され、Dom\DocumentFragmentは空の状態になります。提供されたサンプルコードでは、この「すべての子ノードを削除する」という挙動を具体的に示しています。これは、特定のDOMフラグメントの内容を一括でクリアしたい場合に非常に便利な機能です。

メソッドの戻り値はvoidです。これは、replaceChildren()メソッドが何らかの値を返すのではなく、単にDOM構造の状態を直接変更する操作であることを意味します。このメソッドを使うことで、既存の要素を一度に効率的に置換または削除し、DOM操作のコードを簡潔に保つことができます。

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::replaceChildren() メソッドの使用例。
5 * このメソッドは、DOMドキュメントフラグメント内の既存のすべての子ノードを
6 * 新しいノード（または文字列）に置き換えます。
7 * PHP 8.0 以降で利用可能です。
8 */
9
10// Dom\Document のインスタンスを作成します。
11// Dom\DocumentFragment は、Dom\Document のコンテキスト内で作成されます。
12$document = new Dom\Document();
13
14// Dom\DocumentFragment のインスタンスを作成します。
15// DocumentFragment は、親を持たない軽量なコンテナで、
16// 複数のノードを一時的に格納し、まとめて操作するのに便利です。
17$fragment = $document->createDocumentFragment();
18
19// 初期の子ノードを追加します
20$p1 = $document->createElement('p', 'これは最初の段落です。');
21$p2 = $document->createElement('p', 'これは二番目の段落です。');
22$fragment->append($p1, $p2);
23
24echo "--- 置換前 ---" . PHP_EOL;
25// 現在のフラグメントの内容をHTML形式で出力します。
26// Dom\DocumentFragment は saveHTML() を直接持たないため、
27// Dom\Document を介してHTMLを生成します。
28echo $fragment->saveHTML() . PHP_EOL . PHP_EOL;
29
30// Dom\DocumentFragment::replaceChildren() メソッドを使用して、
31// 既存のすべての子ノードを新しい子ノードで置き換えます。
32// 引数には Dom\Node オブジェクト、または文字列を複数指定できます。
33// 指定されたノードや文字列が、フラグメントの新しい子ノードになります。
34$span = $document->createElement('span', '新しいスパン要素です。');
35$div = $document->createElement('div', '新しいdiv要素です。');
36
37$fragment->replaceChildren(
38    $span,                            // 新しい Dom\Element ノード
39    'そして、これは新しいテキストノードです。', // 文字列も直接指定可能
40    $div                              // 別の新しい Dom\Element ノード
41);
42
43echo "--- 置換後 ---" . PHP_EOL;
44// 置換後のフラグメントの内容をHTML形式で出力します。
45echo $fragment->saveHTML() . PHP_EOL;
46
47// このコードを実行すると、元々あった2つの <p> 要素が、
48// 新しい <span> 要素、テキストノード、および <div> 要素に完全に置き換わっていることが確認できます。
49// これは、HTMLの特定の部分を効率的に更新する際に役立ちます。
50

このPHPサンプルコードは、Dom\DocumentFragment::replaceChildren()メソッドの使い方を示しています。このメソッドは、指定されたDom\DocumentFragmentインスタンスが持つ既存のすべての子ノードを、新しいノードや文字列で完全に置き換えるために使用され、PHP 8.0以降で利用可能です。

まず、Dom\DocumentとDom\DocumentFragmentのインスタンスを作成します。Dom\DocumentFragmentは、親を持たない軽量なコンテナで、複数のノードを一時的に格納し、まとめて操作するのに便利です。初期状態として、2つの<p>要素をフラグメントに追加し、その内容を出力して置換前を確認しています。

次に、replaceChildren()メソッドを呼び出し、新しい<span>要素、直接指定したテキストノード、および新しい<div>要素を引数として渡しています。引数には、Dom\Nodeオブジェクト（HTML要素など）や文字列を複数指定することが可能です。これらがフラグメントの新しい子ノードとして設定されます。このメソッドは直接フラグメントの子ノードを変更するため、戻り値はありません（void）。

コードの実行結果として、置換前には2つの<p>要素が表示され、置換後には<span>要素、テキストノード、<div>要素が新しく表示されることを確認できます。この機能は、HTMLの特定の部分を動的に効率良く更新したい場合に非常に役立ちます。