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

Copy
1<?php
2
3// ドキュメントフラグメントを正規化する例
4$dom = new DOMDocument();
5$fragment = $dom->createDocumentFragment();
6
7// テキストノードを2つ追加
8$fragment->appendChild($dom->createTextNode("Hello, "));
9$fragment->appendChild($dom->createTextNode("World!"));
10
11// 正規化前のドキュメントフラグメントの内容を表示
12echo "正規化前: " . $fragment->textContent . "\n";
13
14// ドキュメントフラグメントを正規化
15$fragment->normalize();
16
17// 正規化後のドキュメントフラグメントの内容を表示
18echo "正規化後: " . $fragment->textContent . "\n";
19
20// 正規化されたドキュメントフラグメントをドキュメントに追加
21$dom->appendChild($fragment);
22
23// ドキュメントの内容を表示
24echo "ドキュメントの内容: " . $dom->saveHTML() . "\n";
25
26?>

PHPのDom\DocumentFragmentクラスのnormalizeメソッドは、ドキュメントフラグメント内のテキストノードを正規化するために使用されます。このメソッドは引数を取らず、戻り値もありません(void)。

具体的には、隣接するテキストノードを結合し、空のテキストノードを削除します。この処理によって、ドキュメントフラグメントの構造が整理され、より扱いやすくなります。

サンプルコードでは、まずDOMDocumentオブジェクトを作成し、それからcreateDocumentFragmentメソッドでドキュメントフラグメントを生成しています。次に、appendChildメソッドを使用して、"Hello, "と "World!"という2つのテキストノードをドキュメントフラグメントに追加しています。

normalizeメソッドを呼び出す前に、textContentプロパティでドキュメントフラグメントの内容を表示し、正規化前の状態を確認します。その後、normalizeメソッドを呼び出してドキュメントフラグメントを正規化します。

正規化後、再度textContentプロパティで内容を表示すると、隣接していた2つのテキストノードが結合され、"Hello, World!"という一つのテキストノードになっていることが確認できます。

最後に、正規化されたドキュメントフラグメントをDOMDocumentオブジェクトに追加し、saveHTMLメソッドでドキュメント全体の内容を表示しています。これにより、正規化されたテキストノードがドキュメントに正しく追加されていることを確認できます。normalizeメソッドは、XMLドキュメントを操作する際に、ノードの構造を最適化するために非常に有効です。

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::normalize() メソッドの動作を示すサンプルコードです。
5 *
6 * normalize() メソッドは、DOMツリー内の隣接するTextノードを結合し、
7 * 空のTextノードを削除することで、ツリーを「正規化」します。
8 * これは、手動でDOMを操作した際に発生しがちな余分なテキストノードをクリーンアップするのに役立ちます。
9 *
10 * 注: PHPのDOM拡張機能は通常、追加のインストールなしで利用できます。
11 */
12function demonstrateDomFragmentNormalization(): void
13{
14    // Dom\Document インスタンスを作成します。
15    // Dom\DocumentFragment は独立した文書ではないため、Dom\Document から作成するのが一般的です。
16    $dom = new Dom\Document('1.0', 'UTF-8');
17
18    // Dom\DocumentFragment を作成します。
19    $fragment = $dom->createDocumentFragment();
20
21    // 正規化前と後で変化がわかるように、複数の隣接するテキストノードと空のテキストノードを追加します。
22    $fragment->appendChild($dom->createTextNode('Hello'));
23    $fragment->appendChild($dom->createTextNode(' ')); // スペースもテキストノードとして扱われます
24    $fragment->appendChild($dom->createTextNode('World!'));
25    $fragment->appendChild($dom->createElement('br')); // 要素ノードを挟む
26    $fragment->appendChild($dom->createTextNode('This is '));
27    $fragment->appendChild($dom->createTextNode('a test.'));
28    $fragment->appendChild($dom->createTextNode('')); // 空のテキストノード
29
30    echo "--- 正規化前の Dom\DocumentFragment の内容 ---\n";
31    // Dom\DocumentFragment は直接XMLとして出力するメソッドを持たないため、
32    // 各子ノードを巡回して種類と内容を表示します。
33    displayFragmentNodes($fragment);
34
35    // Dom\DocumentFragment の normalize メソッドを呼び出します。
36    // これにより、隣接するテキストノードが結合され、空のテキストノードが削除されます。
37    echo "\n--- Dom\\DocumentFragment::normalize() を呼び出し中 ---\n";
38    $fragment->normalize();
39
40    echo "\n--- 正規化後の Dom\DocumentFragment の内容 ---\n";
41    displayFragmentNodes($fragment);
42
43    // さらに、完全に空のテキストノードのみのフラグメントの例も示します。
44    $emptyTextFragment = $dom->createDocumentFragment();
45    $emptyTextFragment->appendChild($dom->createTextNode(''));
46    $emptyTextFragment->appendChild($dom->createTextNode(''));
47    echo "\n--- 空のテキストノードのみのフラグメント (正規化前) ---\n";
48    displayFragmentNodes($emptyTextFragment);
49
50    $emptyTextFragment->normalize();
51    echo "\n--- 空のテキストノードのみのフラグメント (正規化後) ---\n";
52    displayFragmentNodes($emptyTextFragment); // 全ての空ノードが削除されるため、何も表示されなくなる
53}
54
55/**
56 * Dom\DocumentFragment の子ノードを巡回し、その種類と内容を表示するヘルパー関数。
57 *
58 * @param Dom\DocumentFragment $fragment 表示対象のドキュメントフラグメント
59 */
60function displayFragmentNodes(Dom\DocumentFragment $fragment): void
61{
62    if ($fragment->hasChildNodes()) {
63        foreach ($fragment->childNodes as $node) {
64            if ($node instanceof Dom\Text) {
65                echo "  Text Node: '" . $node->nodeValue . "' (Length: " . strlen($node->nodeValue) . ")\n";
66            } elseif ($node instanceof Dom\Element) {
67                echo "  Element Node: <" . $node->tagName . ">\n";
68            } else {
69                echo "  Other Node Type: " . $node->nodeName . "\n";
70            }
71        }
72    } else {
73        echo "  (このフラグメントにはノードがありません)\n";
74    }
75}
76
77// 関数を実行して、Dom\DocumentFragment の正規化の動作を確認します。
78demonstrateDomFragmentNormalization();

Dom\DocumentFragment::normalize()メソッドは、PHPのDOM操作において、DOMツリーを「正規化」するために使用されます。正規化とは、具体的には、隣接する複数のテキストノードを一つのテキストノードに結合し、また内容が空のテキストノードを削除する処理のことです。これにより、手動でDOMを生成したり操作したりする際に発生しがちな、余分なテキストノードを効率的にクリーンアップし、DOMツリーの構造を簡潔に保つのに役立ちます。

このメソッドは引数を一切取らず、処理が完了すると何も値を返しません（void）。つまり、メソッドを呼び出すだけでフラグメントの内容が直接変更されます。

提供されたサンプルコードでは、まずDom\DocumentFragmentを作成し、「Hello」「 」「World!」といった隣接するテキストノードや、内容が空のテキストノードを追加しています。その後、normalize()メソッドを呼び出す前と後で、フラグメントの子ノードの状態を比較しています。これにより、複数のテキストノードが「Hello World!」のように一つに結合され、空のテキストノードが削除される様子が明確に示されます。要素ノードは正規化の対象外となります。

この機能を利用するPHPのDOM拡張機能は、通常、PHPの標準インストールに含まれており、追加でインストールする手間はほとんどありません。

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::normalize メソッドの動作をデモンストレーションする関数。
5 *
6 * このメソッドは、DOMツリー内の隣接するテキストノードを結合し、
7 * 空のテキストノードを削除することで、ツリーを正規化します。
8 * これは、後続の処理でDOMツリーの構造を簡素化するのに役立ちます。
9 */
10function demonstrateDocumentFragmentNormalize(): void
11{
12    // 1. Dom\Document オブジェクトを作成します。
13    // DocumentFragmentは単独では存在できず、常にDocumentに関連付けられています。
14    $dom = new Dom\Document();
15
16    // 2. Dom\DocumentFragment オブジェクトを作成します。
17    // これは、DOMツリーの一部を一時的に保持するための軽量なコンテナです。
18    $fragment = $dom->createDocumentFragment();
19
20    // 3. 意図的に隣接する複数のテキストノードと空のテキストノードをフラグメントに追加します。
21    // これらは normalize() メソッドによって結合または削除されることを期待します。
22    $fragment->appendChild($dom->createTextNode("Hello"));
23    $fragment->appendChild($dom->createTextNode(" ")); // スペースも別ノードとして追加
24    $fragment->appendChild($dom->createTextNode("World"));
25    $fragment->appendChild($dom->createTextNode("!"));
26    $fragment->appendChild($dom->createTextNode("")); // 空のテキストノード
27
28    echo "--- normalize() 呼び出し前の状態 ---" . PHP_EOL;
29    echo "ノード数: " . $fragment->childNodes->length . PHP_EOL;
30    foreach ($fragment->childNodes as $index => $node) {
31        if ($node instanceof Dom\Text) {
32            echo "  ノード " . ($index + 1) . " (Text): '" . $node->nodeValue . "'" . PHP_EOL;
33        } else {
34            echo "  ノード " . ($index + 1) . " (Element): " . $node->nodeName . PHP_EOL;
35        }
36    }
37    echo PHP_EOL;
38
39    // 4. normalize() メソッドを呼び出してフラグメントを正規化します。
40    // このメソッドは void を返し、オブジェクトの内部状態を変更します。
41    $fragment->normalize();
42
43    echo "--- normalize() 呼び出し後の状態 ---" . PHP_EOL;
44    echo "ノード数: " . $fragment->childNodes->length . PHP_EOL;
45    foreach ($fragment->childNodes as $index => $node) {
46        if ($node instanceof Dom\Text) {
47            echo "  ノード " . ($index + 1) . " (Text): '" . $node->nodeValue . "'" . PHP_EOL;
48        } else {
49            echo "  ノード " . ($index + 1) . " (Element): " . $node->nodeName . PHP_EOL;
50        }
51    }
52    echo PHP_EOL;
53
54    // 結果として、複数のテキストノードが1つのテキストノードに結合され、
55    // 空のテキストノードは削除されていることを確認できます。
56}
57
58// サンプル関数を実行します。
59demonstrateDocumentFragmentNormalize();

PHPのDom\DocumentFragment::normalizeメソッドは、DOM（Document Object Model）ツリーの構造を整理し、その後の処理を簡素化するために使用されます。このメソッドは、引数を一切取らず、自身のオブジェクト（Dom\DocumentFragment）の内部状態を直接変更します。そのため、戻り値はvoidとなり、特定の値を返しません。

具体的には、隣接する複数のテキストノードを一つに結合し、内容が空のテキストノードを削除する役割があります。例えば、「Hello」というテキストノードと「 World」というテキストノードが並んでいた場合、normalize()を実行すると「Hello World」という一つのテキストノードにまとめられます。また、追加されたものの内容が空であるテキストノードは、この処理によって自動的に削除されます。

サンプルコードでは、意図的に複数のテキストノードや空のテキストノードを含むDom\DocumentFragmentを作成し、normalize()メソッドの呼び出し前後でノード数がどのように変化するかを示しています。これにより、複雑になりがちなDOMツリーをクリーンな状態に保ち、その後のデータ操作や表示処理をより効率的かつ安全に行うことが可能になります。