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

firstElementChildプロパティの使い方について、初心者にもわかりやすく解説します。

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

基本的な使い方

firstElementChildプロパティは、Dom\HTMLDocumentクラスのインスタンスが表すHTMLドキュメント、またはDom\Elementインスタンスが表す要素の、最初の子要素ノードを保持するプロパティです。このプロパティを使用すると、指定された要素の直下にある最初の子要素に直接アクセスすることができます。

このプロパティの重要な特徴は、空白文字やコメントノードといった非要素ノードを無視し、純粋な要素ノードのみを対象とすることです。例えば、HTMLの<body>タグの直後に改行やインデントがあっても、それらは無視され、最初に出現する実際のHTML要素（例：<p>、<div>、<h1>など）が取得されます。これにより、開発者は意図しない空白やコメントに影響されることなく、構造的な子要素に直接アクセスできるため、DOM操作のコードがよりシンプルかつ堅牢になります。

もし対象の要素に子要素が存在しない場合、このプロパティはnullを返します。そのため、プロパティの戻り値がnullでないことを確認してから、取得した要素に対して操作を行うことが推奨されます。

このプロパティは、HTMLドキュメントの構造を解析し、特定の部分にアクセスしたり、コンテンツを動的に変更したりする際に非常に役立ちます。例えば、ウェブページの特定のセクションの最初の子要素を取得し、そこからさらに目的の要素を探索するといった、DOMツリーの走査の出発点として利用されます。これは、ウェブアプリケーション開発やスクレイピングなど、HTMLドキュメントをプログラムで操作するシステム開発において、頻繁に利用される基本的な機能の一つです。

構文(syntax)


1<?php
2
3$document = new Dom\HTMLDocument();
4$document->loadHTML('<!DOCTYPE html><html><body><p>Content</p></body></html>');
5
6$firstElementChild = $document->firstElementChild;
7
8if ($firstElementChild) {
9    echo $firstElementChild->tagName; // この例では "html" を出力します
10}
11
12?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

?Dom\Element

このプロパティは、対象のHTML要素の最初の子要素であるDom\Elementオブジェクトを返します。子要素が存在しない場合はnullを返します。

サンプルコード

PHP Dom\HTMLDocumentのfirstElementChildを取得する


1<?php
2
3/**
4 * Dom\HTMLDocument::firstElementChild プロパティの使用例を示します。
5 * HTMLドキュメントの最初の要素の子ノード（通常は <html> 要素）を取得します。
6 *
7 * @return void
8 */
9function exampleFirstElementChild(): void
10{
11    // 新しいHTMLドキュメントインスタンスを作成します。
12    $document = new Dom\HTMLDocument();
13
14    // 簡単なHTML文字列をドキュメントにロードします。
15    // これにより、ドキュメントツリーが構築されます。
16    $htmlContent = '<!DOCTYPE html>
17<html>
18<head>
19    <title>サンプルページ</title>
20</head>
21<body>
22    <h1>ようこそ</h1>
23    <p>これはDom\HTMLDocumentのサンプルです。</p>
24</body>
25</html>';
26    $document->loadHTML($htmlContent);
27
28    // ドキュメントの最初の要素の子ノードを取得します。
29    // 通常、これは <html> 要素になります。
30    $firstElement = $document->firstElementChild;
31
32    // 取得した要素が存在するかどうかを確認します。
33    if ($firstElement instanceof Dom\Element) {
34        echo "ドキュメントの最初の要素の子ノードのタグ名: " . $firstElement->tagName . PHP_EOL;
35        // テキストコンテンツが長い場合があるため、一部のみ表示します。
36        echo "ドキュメントの最初の要素の子ノードのtextContent (一部): " . substr($firstElement->textContent, 0, 100) . "..." . PHP_EOL;
37
38        // さらに、取得した要素 (<html>) の最初の要素の子ノードを取得することもできます。
39        // この場合、<html> 要素の最初の子ノードである <head> 要素が取得されます。
40        $htmlFirstChild = $firstElement->firstElementChild;
41        if ($htmlFirstChild instanceof Dom\Element) {
42            echo "<html> 要素の最初の要素の子ノードのタグ名: " . $htmlFirstChild->tagName . PHP_EOL;
43        } else {
44            echo "<html> 要素には要素の子ノードが見つかりませんでした。" . PHP_EOL;
45        }
46    } else {
47        echo "ドキュメントに最初の要素の子ノードが見つかりませんでした。" . PHP_EOL;
48    }
49}
50
51// サンプル関数を実行します。
52exampleFirstElementChild();
53

PHPのDom\HTMLDocument::firstElementChildプロパティは、HTMLドキュメントのツリー構造において、文書の最も外側にある要素の子ノードを取得するために使用されます。通常、これはHTMLドキュメント全体のルートとなる<html>要素を指します。このプロパティは引数を取らず、戻り値としてDom\Elementオブジェクトを返しますが、ドキュメントに要素が存在しない場合はnullを返す可能性があるため、型は?Dom\Elementと表記されます。

サンプルコードでは、まず新しいDom\HTMLDocumentインスタンスを作成し、簡単なHTML文字列をloadHTMLメソッドで読み込んでいます。これにより、ドキュメントの内部にHTML構造が構築されます。次に、$document->firstElementChildを通じて、このドキュメントの最初の要素の子ノードを取得しています。この場合、ロードされたHTMLの<html>タグが取得されます。

取得された$firstElementがDom\Elementのインスタンスであるかを確認した後、その要素のタグ名 (tagName) やテキストコンテンツの一部 (textContent) を表示しています。これにより、実際に<html>要素が取得されていることが確認できます。さらに、取得した<html>要素から再度firstElementChildプロパティを利用することで、その<html>要素内の最初の子要素、つまり<head>要素を取得する例も示しており、このプロパティが要素ツリーをたどるのに便利であることを示しています。

Dom\HTMLDocument::firstElementChildプロパティは、HTMLドキュメントが適切にロードされた後、そのドキュメントの最初の要素の子ノード（通常は<html>要素）を取得します。このプロパティの戻り値はDom\Elementオブジェクトまたはnullの可能性があるため、サンプルコードのように必ずinstanceof Dom\Elementで型を確認し、要素が見つからなかった場合の処理を記述してください。特に、HTMLが空であったり、有効な要素を含まない場合にnullが返される可能性があります。また、このプロパティは要素ノードのみを対象とし、テキストノードやコメントノードはスキップされる点も重要です。常に戻り値を確認することで、意図しないエラーを防ぎ、より堅牢なプログラムを作成できます。

PHP DOM: firstElementChildとfirstChildの違いを理解する


1<?php
2
3/**
4 * Dom\HTMLDocumentのfirstElementChildプロパティとfirstChildプロパティの動作を示します。
5 *
6 * firstElementChildは最初の子要素ノードのみを返しますが、
7 * firstChildは最初の子ノード（コメント、テキスト、要素など）を返します。
8 * これは、システムエンジニアを目指す初心者がDOM操作の基本的な違いを理解するのに役立ちます。
9 */
10function demonstrateFirstElements(): void
11{
12    // 処理対象のHTML文字列を定義します。
13    // コメントノードやテキストノードが含まれていることに注意してください。
14    $htmlString = <<<HTML
15<!DOCTYPE html>
16<html>
17<head>
18    <title>First Element Child Example</title>
19</head>
20<body>
21    <!-- これは、<body>内の最初のノードであるコメントノードです -->
22    最初のテキストノード
23    <p>これは、<body>内の最初の要素ノードであるpタグです。</p>
24    <div>2番目の要素ノード</div>
25</body>
26</html>
27HTML;
28
29    // Dom\HTMLDocumentオブジェクトを作成し、HTML文字列を読み込みます。
30    $document = new Dom\HTMLDocument();
31    $document->loadHTML($htmlString);
32
33    echo "--- ドキュメントの直下 ---" . PHP_EOL;
34
35    // ドキュメントの直下にある最初の子要素ノードを取得します（通常は <html>）。
36    $rootFirstElementChild = $document->firstElementChild;
37    echo "document->firstElementChild (要素ノード): " . ($rootFirstElementChild ? $rootFirstElementChild->nodeName : "なし") . PHP_EOL;
38
39    // ドキュメントの直下にある最初の子ノードを取得します（<!DOCTYPE html>宣言ノード）。
40    $rootFirstChild = $document->firstChild;
41    echo "document->firstChild (任意のノード): " . ($rootFirstChild ? $rootFirstChild->nodeName : "なし") . PHP_EOL;
42
43    echo PHP_EOL;
44    echo "--- <body>要素の直下 ---" . PHP_EOL;
45
46    // ドキュメントから<body>要素を取得します。
47    $bodyElement = $document->body;
48
49    if ($bodyElement) {
50        // <body>要素の直下にある最初の子要素ノード（要素ノードのみ）を取得します。
51        // このHTMLの場合、<p>要素が該当します。
52        $bodyFirstElementChild = $bodyElement->firstElementChild;
53        echo "bodyElement->firstElementChild (要素ノード): " .
54             ($bodyFirstElementChild ? $bodyFirstElementChild->nodeName .
55                                       " (内容: " . mb_substr($bodyFirstElementChild->textContent, 0, 20) . "..." . ")"
56                                     : "なし") . PHP_EOL;
57
58        // <body>要素の直下にある最初の子ノード（コメント、テキスト、要素など）を取得します。
59        // このHTMLの場合、コメントノードが該当します。
60        $bodyFirstChild = $bodyElement->firstChild;
61        echo "bodyElement->firstChild (任意のノード): " .
62             ($bodyFirstChild ? $bodyFirstChild->nodeName .
63                                 " (内容: " . ($bodyFirstChild instanceof Dom\Comment ? $bodyFirstChild->data : mb_substr($bodyFirstChild->textContent, 0, 20) . "...") . ")"
64                               : "なし") . PHP_EOL;
65
66        echo PHP_EOL;
67        echo "--- firstElementChild と firstChild の違いについて ---" . PHP_EOL;
68        echo "・firstElementChild は、対象要素の直下にある子要素ノードのうち、最初に現れるものを返します。" . PHP_EOL;
69        echo "・firstChild は、対象要素の直下にある子ノードのうち、最初に現れるものを返します。これには、コメントノードやテキストノードなども含まれます。" . PHP_EOL;
70
71    } else {
72        echo "エラー: <body>要素が見つかりませんでした。" . PHP_EOL;
73    }
74}
75
76// サンプル関数を実行して動作を確認します。
77demonstrateFirstElements();

PHPのDom\HTMLDocumentクラスは、HTMLドキュメントをオブジェクトとして扱い、その構造をプログラムから操作するための機能を提供します。このクラスのfirstElementChildプロパティは、HTMLドキュメントや特定の要素の直下にある最初の子要素ノードを取得するために使用されます。引数は必要なく、戻り値として、最初の子要素ノードが見つかった場合はDom\Elementオブジェクトを、見つからなかった場合はnullを返します。

このプロパティの重要な点は、要素ノード（HTMLタグ）のみを対象とすることです。一方、firstChildプロパティは、コメントノード、テキストノード、要素ノードなど、ノードの種類を問わず最初の子ノードを返します。

提供されたサンプルコードでは、firstElementChildとfirstChildのこの違いを具体的に示しています。HTML文字列をDom\HTMLDocumentオブジェクトに読み込んだ後、ドキュメントの直下や<body>要素の直下でこれらのプロパティを呼び出しています。例えば、<body>要素の開始直後にコメントやテキストが存在する場合、firstChildはそれらを最初のノードとして返しますが、firstElementChildはそれらをスキップし、最初に見つかる<p>タグなどの要素ノードを返します。この挙動の理解は、HTML構造を正確に操作する上で非常に重要です。

firstElementChildはHTMLタグで定義される「要素ノード」のみを返しますが、firstChildは要素ノードに加えて、HTML内の改行、空白、コメントなど「あらゆる種類のノード」を返します。この違いを理解しないと、意図しないノードを取得してしまうため、DOM操作では特に注意が必要です。

どちらのプロパティも、対象の子ノードが存在しない場合はnullを返します。そのため、取得した結果を使用する前には、必ずnullチェックを行い、ノードが存在することを確認してから処理を進めてください。これにより、予期せぬエラーを防ぎ、安全なコードを記述できます。