【PHP8.x】DOMDocumentFragment::firstElementChildプロパティの使い方

Copy
1<?php
2
3/**
4 * DOMDocumentFragment の firstElementChild プロパティの動作を実演します。
5 *
6 * firstElementChild は、DOMDocumentFragment の最初の子要素 (DOMElement) を返します。
7 * 子要素が存在しない場合や、最初の子ノードが要素でない場合は null を返します。
8 */
9function demonstrateDomDocumentFragmentFirstElementChild(): void
10{
11    // 新しい DOMDocumentFragment を作成します。
12    $fragment = new DOMDocumentFragment();
13
14    // いくつかのノードを作成し、フラグメントに追加します。
15    // テキストノードは要素ではないため、firstElementChild には含まれません。
16    $textNode = new DOMText('これはただのテキストノードです。');
17    $paragraphElement = new DOMElement('p', 'これは最初の要素です。');
18    $divElement = new DOMElement('div', 'これは二番目の要素です。');
19
20    // フラグメントにノードを追加します。追加順序が重要です。
21    $fragment->appendChild($textNode);        // 最初のノードはテキスト
22    $fragment->appendChild($paragraphElement); // その次のノードが最初の要素
23    $fragment->appendChild($divElement);
24
25    echo "--- DOMDocumentFragment に要素がある場合 ---\n";
26
27    // firstElementChild プロパティを使用して、最初の要素の子を取得します。
28    $firstElement = $fragment->firstElementChild;
29
30    // 取得したノードが DOMElement のインスタンスであるか確認します。
31    if ($firstElement instanceof DOMElement) {
32        echo "最初の要素は: <" . $firstElement->tagName . ">\n";
33        echo "そのテキストコンテンツは: '" . $firstElement->textContent . "'\n";
34    } else {
35        echo "フラグメント内に要素が見つかりませんでした。\n";
36    }
37
38    echo "\n--- DOMDocumentFragment に要素がない場合 ---\n";
39
40    // 要素を含まない新しい DOMDocumentFragment を作成します。
41    $emptyFragment = new DOMDocumentFragment();
42    $emptyFragment->appendChild(new DOMText('ここには要素がありません。'));
43    $emptyFragment->appendChild(new DOMComment('これはコメントです。'));
44
45    // firstElementChild を再度試します。
46    $noElements = $emptyFragment->firstElementChild;
47
48    if ($noElements instanceof DOMElement) {
49        echo "予期せず要素が見つかりました: <" . $noElements->tagName . ">\n";
50    } else {
51        echo "正しく、フラグメント内に要素が見つかりませんでした。\n";
52    }
53}
54
55// 関数を実行して動作を確認します。
56demonstrateDomDocumentFragmentFirstElementChild();

PHP 8 の DOMDocumentFragment クラスに属する firstElementChild プロパティは、その DOMDocumentFragment オブジェクト内に含まれる最初の子要素（DOMElement）を取得するために使用されます。このプロパティは引数を取りません。戻り値は、フラグメント内に最初の子要素が見つかればその DOMElement オブジェクトを返し、見つからない場合や、最初の子ノードが要素ではない（例えばテキストノードやコメントノードなど）場合は null を返します。

提供されたサンプルコードでは、この動作が具体的な例で示されています。最初のケースでは、DOMDocumentFragment にテキストノード、その後に <p> 要素、さらに <div> 要素を追加しています。firstElementChild プロパティを呼び出すと、最初の子ノードがテキストノードであったとしても、最初に見つかる「要素」である <p> タグの DOMElement オブジェクトが返されます。これにより、その要素名「p」やテキスト内容「これは最初の要素です。」が正確に取得・表示される様子が確認できます。

二番目のケースでは、要素を一切含まない DOMDocumentFragment を作成し、テキストノードとコメントノードのみを追加しています。これらのノードは要素ではないため、firstElementChild プロパティを呼び出すと期待通り null が返されます。このプロパティは、DOMツリーの操作において、最初の子要素を効率的かつ確実に特定する際に非常に便利です。

Copy
1<?php
2
3/**
4 * DOMDocumentFragment::firstElementChild プロパティの使用方法をデモンストレーションします。
5 *
6 * firstElementChild は、DOMDocumentFragment の最初の子要素 (DOMElement) を返します。
7 * 子要素が存在しない場合、または最初の子ノードが要素でない場合は null を返します。
8 * 比較のために firstChild も示し、その違いを明確にします。
9 */
10function demonstrateFirstElementChild(): void
11{
12    // 新しい DOM ドキュメントを作成します。DOMDocumentFragment を作成するために必要です。
13    $dom = new DOMDocument();
14
15    // DOMDocumentFragment を作成します。これは、XML または HTML の断片を保持する特殊なノードです。
16    $fragment = $dom->createDocumentFragment();
17
18    echo "--- 混合コンテンツを持つフラグメント --- \n";
19
20    // テキストノードを追加します (最初の子ノードになるが、要素ではない)。
21    $fragment->appendChild($dom->createTextNode("  最初のテキストノード  "));
22    // コメントノードを追加します (これも要素ではない)。
23    $fragment->appendChild($dom->createComment("これはコメントです"));
24    // 最初の子要素となる DIV 要素を追加します。
25    $divElement = $dom->createElement('div');
26    $divElement->textContent = 'これが最初の要素です';
27    $fragment->appendChild($divElement);
28    // その他の要素を追加します。
29    $spanElement = $dom->createElement('span');
30    $spanElement->textContent = 'これは2番目の要素です';
31    $fragment->appendChild($spanElement);
32
33    // firstElementChild プロパティにアクセスします。
34    // これは、追加された最初の DOMElement である $divElement を返します。
35    $firstElement = $fragment->firstElementChild;
36
37    if ($firstElement instanceof DOMElement) {
38        echo "firstElementChild で見つかったノード名: " . $firstElement->nodeName . "\n";
39        echo "firstElementChild で見つかったテキスト内容: " . $firstElement->textContent . "\n";
40    } else {
41        echo "firstElementChild は null です (子要素が見つかりませんでした)。\n";
42    }
43
44    // 比較のために firstChild プロパティにアクセスします。
45    // これは、フラグメント内の最初のノードである DOMText ノードを返します。
46    $firstChild = $fragment->firstChild;
47
48    if ($firstChild) {
49        echo "firstChild で見つかったノード名: " . $firstChild->nodeName . "\n";
50        echo "firstChild で見つかったテキスト内容 (一部): '" . substr($firstChild->textContent, 0, 20) . "...'\n";
51    } else {
52        echo "firstChild は null です (子ノードが見つかりませんでした)。\n";
53    }
54
55    echo "\n--- 要素を含まないフラグメント --- \n";
56
57    $noElementsFragment = $dom->createDocumentFragment();
58    // 要素ではないノードのみを追加します。
59    $noElementsFragment->appendChild($dom->createComment("単なるコメント"));
60    $noElementsFragment->appendChild($dom->createTextNode("さらにテキスト"));
61
62    // firstElementChild は null を返します。なぜなら、フラグメントに要素が含まれていないからです。
63    $firstElementNoElements = $noElementsFragment->firstElementChild;
64    if ($firstElementNoElements instanceof DOMElement) {
65        echo "firstElementChild で見つかったノード名: " . $firstElementNoElements->nodeName . "\n";
66    } else {
67        echo "firstElementChild は null です (期待通り、要素が見つかりませんでした)。\n";
68    }
69
70    // firstChild は最初のノードであるコメントノードを返します。
71    $firstChildNoElements = $noElementsFragment->firstChild;
72    if ($firstChildNoElements) {
73        echo "firstChild で見つかったノード名: " . $firstChildNoElements->nodeName . "\n";
74        echo "firstChild で見つかったテキスト内容: '" . $firstChildNoElements->textContent . "'\n";
75    } else {
76        echo "firstChild は null です。\n";
77    }
78
79    echo "\n--- 空のフラグメント --- \n";
80
81    $emptyFragment = $dom->createDocumentFragment();
82
83    // 空のフラグメントでは、両方のプロパティが null を返します。
84    $firstElementEmpty = $emptyFragment->firstElementChild;
85    if ($firstElementEmpty instanceof DOMElement) {
86        echo "firstElementChild で見つかったノード名: " . $firstElementEmpty->nodeName . "\n";
87    } else {
88        echo "firstElementChild は null です (期待通り、フラグメントは空です)。\n";
89    }
90
91    $firstChildEmpty = $emptyFragment->firstChild;
92    if ($firstChildEmpty) {
93        echo "firstChild で見つかったノード名: " . $firstChildEmpty->nodeName . "\n";
94    } else {
95        echo "firstChild は null です (期待通り、フラグメントは空です)。\n";
96    }
97}
98
99// デモンストレーション関数を実行します。
100demonstrateFirstElementChild();

PHP 8のDOMDocumentFragment::firstElementChildプロパティは、XMLやHTMLの断片を扱うDOMDocumentFragmentオブジェクトにおいて、その断片内の最初に見つかる子要素（DOMElement型）を取得するために使用されます。このプロパティは引数を取らず、戻り値として最初の子要素をDOMElement型で返します。もし子要素が存在しない場合や、最初の子ノードがテキストノードやコメントノードのような要素以外のノードである場合はnullを返します。

似たプロパティにfirstChildがありますが、firstElementChildとの主な違いは、firstElementChildがノードの種類に関わらず「最初の子要素」のみを対象とする点です。一方、firstChildはテキストノードやコメントノードなども含め、フラグメント内の「最初の子ノード」そのものを返します。

サンプルコードでは、テキストノード、コメントノード、要素を混合して追加したフラグメントを作成し、firstElementChildが最初に追加されたdiv要素を返すのに対し、firstChildは最初のテキストノードを返すことを示しています。さらに、要素を含まないフラグメントや空のフラグメントの例も検証しており、要素が存在しない場合にはfirstElementChildがnullを返す挙動を確認できます。これにより、DOMツリーから特定の要素にのみアクセスしたい場合にfirstElementChildが非常に便利であることが理解できます。