いっしー@Webエンジニア
Webツールプログラミング言語プログラミング学習ITニュースIT用語辞典ポートフォリオ
Webエンジニア向けプログラミング解説動画をYouTubeで配信中！
▶ チャンネル登録はこちら

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

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

作成日: 更新日:

基本的な使い方

querySelectorメソッドは、Dom\HTMLElementオブジェクトが持つ、CSSセレクターに一致する最初の要素を検索し、取得するメソッドです。このメソッドは、呼び出し元のHTML要素を起点として、その子孫要素の中から、指定されたCSSセレクターに合致する要素を効率的に探し出します。

引数には、検索したい要素を表すCSSセレクターを文字列として渡します。例えば、id属性やclass属性、タグ名など、CSSのスタイル指定で使われる記法を用いて、目的の要素を正確に指定することが可能です。

検索が実行され、セレクターに一致する要素が複数見つかった場合でも、このメソッドはDOMツリーの順序で最初に見つかった要素のみをDom\Elementオブジェクトとして返します。もし、指定されたセレクターに一致する要素が一つも見つからなかった場合は、nullが返されます。

このメソッドは、PHPでHTMLドキュメントを解析し、特定のHTML要素の内容を抽出したり、属性値を変更したり、あるいは他の要素を追加したりする際に非常に有用です。これにより、Webページの構造的な操作を効率的かつ直感的に行うことが可能になります。システムエンジニアにとって、HTMLコンテンツの動的な処理や分析を行う上で不可欠な機能の一つです。

構文(syntax)

1<?php
2$elementOrNull = $htmlElement->querySelector($cssSelectorString);

引数(parameters)

string $selectors

  • string $selectors: 検索したい要素を指定するCSSセレクタ文字列

戻り値(return)

?Dom\Element

指定されたCSSセレクターに一致する最初の要素を返します。一致する要素が見つからなかった場合はnullを返します。

サンプルコード

PHP DOM querySelectorで要素を検索する

1<?php
2
3// Dom\HTMLElement::querySelector メソッドの使用例
4// システムエンジニアを目指す初心者向けに、HTML要素をCSSセレクタで選択する方法を示します。
5
6/**
7 * 指定されたHTML文字列から Dom\HTMLElement::querySelector を使用して要素を検索し、情報を表示する関数。
8 *
9 * @param string $html HTMLコンテンツ文字列
10 * @param string $selector CSSセレクタ文字列 (例: '#id', '.class', 'tag', 'tag[attr="value"]')
11 * @return void
12 */
13function findElementByQuerySelector(string $html, string $selector): void
14{
15    // PHP 8 の新しいDOM拡張では Dom\Document を使用してHTMLをパースします。
16    $dom = new Dom\Document();
17
18    // HTMLコンテンツをロードします。@を付けてロードエラーの警告を抑制します。
19    // これにより、不完全なHTMLでもスクリプトが停止することなく実行できます。
20    @$dom->loadHTML($html);
21
22    // Dom\Document::documentElement は、HTMLドキュメントのルート要素 (例: <html>) を表します。
23    // この要素は Dom\HTMLElement のインスタンスであり、querySelector メソッドを持っています。
24    $rootElement = $dom->documentElement;
25
26    // Dom\HTMLElement::querySelector を使用して、指定されたCSSセレクタに一致する最初の要素を検索します。
27    // 戻り値は Dom\Element オブジェクト、または見つからなかった場合は null です。
28    $element = $rootElement->querySelector($selector);
29
30    echo "--- セレクタ: '{$selector}' ---\n";
31
32    if ($element instanceof Dom\Element) { // 要素が見つかった場合の処理
33        echo "  要素が見つかりました。\n";
34        echo "  タグ名: " . $element->tagName . "\n";
35        echo "  テキストコンテンツ: " . trim($element->textContent) . "\n"; // 前後の空白をトリム
36
37        // 要素が属性を持っている場合、それらも表示します。
38        if ($element->hasAttributes()) {
39            echo "  属性:\n";
40            foreach ($element->attributes as $attr) {
41                echo "    - {$attr->name}: {$attr->value}\n";
42            }
43        }
44    } else { // 要素が見つからなかった場合の処理
45        echo "  指定されたセレクタに一致する要素は見つかりませんでした。\n";
46    }
47    echo "\n";
48}
49
50// サンプルとして使用するHTMLコンテンツ
51$sampleHtml = <<<HTML
52<!DOCTYPE html>
53<html>
54<head>
55    <title>Sample Page for querySelector</title>
56</head>
57<body>
58    <div id="main-content">
59        <h1 class="page-title">Welcome to PHP DOM Extension</h1>
60        <p class="intro-text">
61            このサンプルは、Dom\\HTMLElement::querySelector の使い方を示しています。
62            querySelector はCSSセレクタを使って要素を検索します。
63        </p>
64        <ul id="item-list">
65            <li class="list-item first">First item</li>
66            <li class="list-item">Second item</li>
67            <li class="list-item last">Third item</li>
68        </ul>
69        <button class="action-button">Click Me</button>
70        <a href="/about" class="action-link">About Us</a>
71    </div>
72    <div class="footer">
73        <p>Copyright 2023</p>
74    </div>
75</body>
76</html>
77HTML;
78
79// さまざまなCSSセレクタを使って要素を検索する例
80// Dom\HTMLElement::querySelector は、常に最初に見つかった要素のみを返します。
81// 複数の要素を選択したい場合は、Dom\HTMLElement::querySelectorAll を使用します（これは別のメソッドです）。
82
83// 1. IDセレクタで要素を検索
84findElementByQuerySelector($sampleHtml, '#main-content');
85
86// 2. クラスセレクタで要素を検索 (最初に見つかる 'list-item' クラスの要素)
87findElementByQuerySelector($sampleHtml, '.list-item');
88
89// 3. タグ名セレクタで要素を検索 (最初に見つかる 'p' タグの要素)
90findElementByQuerySelector($sampleHtml, 'p');
91
92// 4. 複合セレクタで特定の要素を検索 (IDが 'item-list' の中の 'li.first' クラスの要素)
93findElementByQuerySelector($sampleHtml, '#item-list li.first');
94
95// 5. 属性セレクタで要素を検索 (href属性を持つ 'a' タグの要素)
96findElementByQuerySelector($sampleHtml, 'a[href]');
97
98// 6. 存在しないセレクタで検索
99findElementByQuerySelector($sampleHtml, '#non-existent-id');

PHP 8のDom\HTMLElement::querySelectorメソッドは、HTMLドキュメントからCSSセレクタを使って特定の要素を検索します。このメソッドはDom\HTMLElementクラスに属しており、通常、HTMLドキュメントのルート要素であるDom\Document::documentElementなどから呼び出して使用します。

引数string $selectorsには、IDセレクタ（#id）、クラスセレクタ（.class）、タグ名セレクタ（div）、またはこれらを組み合わせた複合セレクタといった、標準的なCSSセレクタ文字列を指定します。

戻り値は?Dom\Elementです。指定したセレクタに一致する要素が見つかった場合は、その要素を表すDom\Elementオブジェクトが返されますが、一つも要素が見つからなかった場合はnullが返されます。querySelectorの重要な点は、一致する要素が複数存在しても、常に最初に見つかった一つだけを返すことです。複数の要素を一度に取得したい場合は、Dom\HTMLElement::querySelectorAllメソッドを使用してください。

このサンプルコードは、ID、クラス、タグ名、複合セレクタなど、様々なCSSセレクタを用いてHTML文書内の要素を検索し、そのタグ名、テキストコンテンツ、属性などの情報を表示する具体的な方法を示しています。これにより、プログラムからHTML要素を特定し、その内容を取得・操作する基礎を効率的に学習できます。

querySelectorは、指定されたCSSセレクタに最初に見つかる要素のみを返します。複数の要素を選択したい場合は、キーワードにもあるDom\HTMLElement::querySelectorAllメソッドを利用してください。要素が見つからなかった場合、戻り値はnullとなるため、コード例のようにinstanceof Dom\Elementで必ず存在チェックを行いましょう。PHP 8の新しいDOM拡張は、以前のDOM機能とはクラス名などが異なるため、バージョンに応じた公式ドキュメントの確認が重要です。また、@によるエラー抑制は、スクリプト停止を防ぎますが、問題の発見を遅らせる可能性もあるため、本番環境での利用には注意が必要です。

PHP DOMで要素を選択する

1<?php
2
3/**
4 * Dom\HTMLElement::querySelector および Dom\ParentNode::querySelectorAll の使用例。
5 * Dom\HTMLElement は Dom\ParentNode インターフェースを実装しているため、
6 * querySelector と querySelectorAll の両方のメソッドを利用できます。
7 * この例では、まず Dom\Document から特定の Dom\HTMLElement を取得し、
8 * その要素に対してメソッドを呼び出しています。
9 */
10
11// サンプルとなるHTMLコンテンツを定義
12$htmlContent = <<<HTML
13<!DOCTYPE html>
14<html>
15<head>
16    <title>PHP DOM Selector Example</title>
17</head>
18<body>
19    <div id="app-root">
20        <h1>Welcome to the Application</h1>
21        <p class="greeting-message">Hello, system engineer beginner!</p>
22        <ul id="menu-items">
23            <li class="menu-item active">Home</li>
24            <li class="menu-item">About</li>
25            <li class="menu-item">Contact</li>
26            <li>Blog</li>
27        </ul>
28        <button class="action-button primary">Save</button>
29        <button class="action-button">Cancel</button>
30    </div>
31</body>
32</html>
33HTML;
34
35// Dom\Document オブジェクトを作成し、HTMLコンテンツを読み込む
36$document = new Dom\Document();
37// loadHtml() でHTML文字列をパース
38$document->loadHtml($htmlContent);
39
40// まず、操作の起点となる Dom\HTMLElement (id="app-root" の div) を取得します。
41// Dom\Document も Dom\ParentNode を実装しているため querySelector が利用可能です。
42$appRootElement = $document->querySelector('#app-root');
43
44// 取得した要素が Dom\HTMLElement のインスタンスであることを確認
45if ($appRootElement instanceof Dom\HTMLElement) {
46    echo "--- Dom\\HTMLElement (id='app-root') 内での要素選択 ---\n\n";
47
48    // --- Dom\HTMLElement::querySelector の使用例 ---
49    // appRootElement 内で、クラス名が "greeting-message" の最初の p 要素を取得
50    // querySelector は合致する最初の要素のみを返します。
51    $greetingParagraph = $appRootElement->querySelector('p.greeting-message');
52
53    if ($greetingParagraph instanceof Dom\HTMLElement) {
54        echo "1. greeting-message クラスを持つ段落: " . $greetingParagraph->textContent . "\n";
55    } else {
56        echo "1. greeting-message クラスを持つ段落は見つかりませんでした。\n";
57    }
58
59    // --- Dom\ParentNode::querySelectorAll の使用例 (Dom\HTMLElement 経由) ---
60    // appRootElement 内で、クラス名が "menu-item" の全ての li 要素を取得
61    // querySelectorAll は合致する全ての要素を Dom\NodeList オブジェクトとして返します。
62    $menuItems = $appRootElement->querySelectorAll('li.menu-item');
63
64    if ($menuItems->count() > 0) {
65        echo "\n2. menu-item クラスを持つリスト項目:\n";
66        foreach ($menuItems as $item) {
67            // 各要素のテキストコンテンツを表示
68            echo "   - " . $item->textContent . "\n";
69        }
70    } else {
71        echo "\n2. menu-item クラスを持つリスト項目は見つかりませんでした。\n";
72    }
73
74    // 別の querySelectorAll の使用例: 複数のクラスセレクタ
75    // appRootElement 内で、クラス名が "action-button" の全ての button 要素を取得
76    $actionButtons = $appRootElement->querySelectorAll('button.action-button');
77
78    if ($actionButtons->count() > 0) {
79        echo "\n3. action-button クラスを持つボタン:\n";
80        foreach ($actionButtons as $button) {
81            echo "   - " . $button->textContent . "\n";
82        }
83    } else {
84        echo "\n3. action-button クラスを持つボタンは見つかりませんでした。\n";
85    }
86
87} else {
88    echo "指定された ID 'app-root' を持つ要素が見つかりませんでした。\n";
89}
90
91?>

PHPのDom\HTMLElement::querySelectorは、HTML要素の中から、指定したCSSセレクタに合致する最初の要素を検索し、取得するためのメソッドです。ウェブページから特定の情報を抽出したり、動的に要素を操作したりする際に非常に役立ちます。

このメソッドの引数 $selectors には、CSSセレクタ（例: #id名、.クラス名、タグ名）を文字列で指定します。戻り値は、検索に成功した場合にDom\Elementオブジェクトを返しますが、該当する要素が見つからなかった場合はnullを返します。

また、関連するメソッドとしてDom\ParentNode::querySelectorAllがあります。Dom\HTMLElementクラスはDom\ParentNodeインターフェースを実装しているため、このquerySelectorAllメソッドも利用可能です。querySelectorAllは、querySelectorと同様にCSSセレクタで要素を検索しますが、合致する「全ての」要素をDom\NodeListというオブジェクトのリストとして返します。要素が見つからなくても、空のDom\NodeListが返されます。

サンプルコードでは、まずHTML文字列をDom\Documentに読み込み、そこから基準となる要素（IDがapp-rootのdiv）を取得しています。その後、この基準要素に対してquerySelectorを使って特定の段落要素を一つ取得し、querySelectorAllを使って複数のリスト項目やボタン要素をまとめて取得し、その内容を表示しています。これにより、複雑なHTML構造から必要な要素をピンポイントで、あるいはまとめて取得する方法が理解できます。

querySelectorは最初に見つかった要素を一つ返しますが、querySelectorAllは条件に合う要素すべてをDom\NodeListとして返します。要素が見つからない場合、querySelectorはnullを、querySelectorAllは空のリストを返しますので、結果がnullでないか、リストが空でないかの確認が必須です。引数にはCSSセレクタを指定するため、HTML構造を正確に理解し、適切なセレクタを記述する必要があります。これらのDOM操作機能を利用するには、PHPのDOM拡張機能が有効になっていることを事前に確認してください。

関連コンテンツ

関連IT用語

関連プログラミング言語