【PHP8.x】Dom\Entity::DOCUMENT_POSITION_CONTAINS定数の使い方

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較し、DOCUMENT_POSITION_CONTAINS 定数を使って包含関係を判定するサンプルです。
5 *
6 * Dom\Node::compareDocumentPosition() メソッドは、2つのノード間の位置関係を示すビットマスクを返します。
7 * DOCUMENT_POSITION_CONTAINS 定数は、比較対象のノードが基準ノードに含まれている場合にセットされるビットを示します。
8 *
9 * PHP 8において、この定数は Dom\Node クラスに属しています。
10 * (提供されたリファレンス情報では Dom\Entity に所属とありますが、実際のDOM操作では Dom\Node クラスで利用されるのが一般的です。)
11 */
12function demonstrateDomContainsPositionComparison(): void
13{
14    // DOMDocument オブジェクトを生成し、HTMLコンテンツを読み込む
15    $dom = new DOMDocument();
16    // エラーを表示しない設定（DOMDocument::loadHTML の警告を抑制するため）
17    libxml_use_internal_errors(true);
18    $dom->loadHTML('<div><p>Hello <span>World</span></p></div>');
19    libxml_clear_errors(); // 読み込み後のエラーをクリア
20
21    // 目的のDOM要素を取得
22    $divElement = $dom->getElementsByTagName('div')->item(0);
23    $pElement = $dom->getElementsByTagName('p')->item(0);
24    $spanElement = $dom->getElementsByTagName('span')->item(0);
25
26    if (!$divElement || !$pElement || !$spanElement) {
27        echo "必要なDOM要素の取得に失敗しました。HTML構造を確認してください。\n";
28        return;
29    }
30
31    echo "--- ノードの包含関係の比較 ---\n";
32
33    // ケース1: div が p を含んでいるか
34    // div から見て p の位置関係を比較
35    $positionDivToP = $divElement->compareDocumentPosition($pElement);
36    if (($positionDivToP & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
37        echo "1. 'div' は 'p' を含んでいます。\n";
38    } else {
39        echo "1. 'div' は 'p' を含んでいません。\n";
40    }
41
42    // ケース2: p が div を含んでいるか (逆方向)
43    // p から見て div の位置関係を比較
44    $positionPToDiv = $pElement->compareDocumentPosition($divElement);
45    if (($positionPToDiv & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
46        echo "2. 'p' は 'div' を含んでいます。(これは通常、予期しない結果です)\n";
47    } else {
48        echo "2. 'p' は 'div' を含んでいません。\n";
49    }
50
51    // ケース3: p が span を含んでいるか
52    // p から見て span の位置関係を比較
53    $positionPToSpan = $pElement->compareDocumentPosition($spanElement);
54    if (($positionPToSpan & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
55        echo "3. 'p' は 'span' を含んでいます。\n";
56    } else {
57        echo "3. 'p' は 'span' を含んでいません。\n";
58    }
59
60    // ケース4: span が p を含んでいるか (逆方向)
61    // span から見て p の位置関係を比較
62    $positionSpanToP = $spanElement->compareDocumentPosition($pElement);
63    if (($positionSpanToP & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
64        echo "4. 'span' は 'p' を含んでいます。(これは通常、予期しない結果です)\n";
65    } else {
66        echo "4. 'span' は 'p' を含んでいません。\n";
67    }
68}
69
70// 関数を実行
71demonstrateDomContainsPositionComparison();

このPHPサンプルコードは、HTMLのDOM（Document Object Model）ノード間の位置関係、特にあるDOM要素が別のDOM要素の中に含まれているか、といった包含関係を判定する方法を示しています。具体的には、Dom\Node::compareDocumentPosition() メソッドと Dom\Node::DOCUMENT_POSITION_CONTAINS 定数を使用しています。

Dom\Node::compareDocumentPosition() メソッドは、呼び出し元のノード（基準となるノード）と引数で指定されたノード（比較対象のノード）の位置関係を数値（ビットマスク）として返します。この戻り値には、複数の位置関係に関する情報が組み込まれています。

Dom\Node::DOCUMENT_POSITION_CONTAINS 定数は、このビットマスクの一部として、特定の状態を示すための整数値です。この定数が示すビットが、compareDocumentPosition() メソッドの戻り値に含まれている場合、基準ノードが比較対象ノードを「含んでいる」状態であることを意味します。サンプルコードでは、まずDOMDocumentオブジェクトでHTMLを読み込み、div、p、span要素を取得しています。そして、それぞれの要素間の包含関係を compareDocumentPosition() で比較し、この定数を利用する際は、ビットAND演算子 (&) を用いて、compareDocumentPosition() メソッドの戻り値に DOCUMENT_POSITION_CONTAINS が示すビットが含まれているかを確認します。これにより、Webページの構造をプログラム的に分析したり、特定の要素の親子関係を調べたりすることが可能になります。

Copy
1<?php
2
3// このサンプルコードはPHP 8.1以降で利用可能な Dom\ 名前空間のクラスを使用しています。
4// PHP 8.0 以前の場合、グローバル名前空間の DOMDocument や DOMNode クラスを使用してください。
5
6namespace Dom;
7
8/**
9 * リファレンス情報で指定された「Dom\Entity」クラスの例。
10 *
11 * 実際のPHPのDOM拡張にはこの名前のクラスは存在しませんが、
12 * Dom\Node クラスが同様の定数と機能を提供します。
13 * このクラスは、キーワード「phpdoc const」に合わせ、定数のPHPDoc記述例を示すために定義されています。
14 */
15class Entity
16{
17    /**
18     * @const int DOCUMENT_POSITION_CONTAINS
19     * 比較対象のノードが、参照ノードを内包していることを示すビットマスク定数。
20     *
21     * この定数は、Dom\Node::compareDocumentPosition メソッドの戻り値と組み合わせて使用されます。
22     * 値は 0x08 (十進数で 8) で、組み込みの Dom\Node::DOCUMENT_POSITION_CONTAINS 定数と同じです。
23     *
24     * このPHPDocブロックは、クラスの定数に対してどのようにPHPDocを記述するかを示しています。
25     */
26    public const DOCUMENT_POSITION_CONTAINS = 0x08; // 組み込み定数 Dom\Node::DOCUMENT_POSITION_CONTAINS と同じ値
27
28    // このクラス自体はDOMノードの比較機能を持たないため、
29    // 定義された定数とPHPDocの例に焦点を当てます。
30}
31
32/**
33 * Dom\Entity::DOCUMENT_POSITION_CONTAINS 定数の意味と利用方法を示すためのヘルパークラス。
34 * 実際のノード比較には、Dom\Node クラスの compareDocumentPosition メソッドと
35 * Dom\Node::DOCUMENT_POSITION_CONTAINS 組み込み定数を使用します。
36 */
37class DocumentPositionChecker
38{
39    /**
40     * 二つのDOMノード間の位置関係を比較し、一方のノードがもう一方を含んでいるかを表示します。
41     *
42     * @param \Dom\Node $node1 比較する最初のノード（基準となるノード）
43     * @param \Dom\Node $node2 比較する2番目のノード
44     * @return void
45     */
46    public function checkContains(\Dom\Node $node1, \Dom\Node $node2): void
47    {
48        echo "ノード '{$node1->nodeName}' がノード '{$node2->nodeName}' を含んでいるか確認:\n";
49
50        // Dom\Node::compareDocumentPosition メソッドは、ノード間の相対的な位置関係を
51        // 示すビットマスク（整数の組み合わせ）を返します。
52        $position = $node1->compareDocumentPosition($node2);
53
54        // 返されたビットマスクに対して、Dom\Node::DOCUMENT_POSITION_CONTAINS 定数を
55        // ビットAND演算子 (&) で確認することで、包含関係にあるか判断できます。
56        // ここでは、Dom\Entity::DOCUMENT_POSITION_CONTAINS ではなく、
57        // 実際のDOM操作で利用される Dom\Node::DOCUMENT_POSITION_CONTAINS を使用します。
58        if ($position & \Dom\Node::DOCUMENT_POSITION_CONTAINS) {
59            echo "  - はい、ノード '{$node1->nodeName}' はノード '{$node2->nodeName}' を含んでいます。\n";
60        } else {
61            echo "  - いいえ、ノード '{$node1->nodeName}' はノード '{$node2->nodeName}' を含んでいません。\n";
62        }
63        echo "  (比較結果ビットマスク: " . sprintf("0x%x", $position) . ")\n";
64    }
65
66    /**
67     * このサンプルの実行エントリポイントです。
68     * 簡単なDOMツリーを構築し、ノード間の包含関係を比較します。
69     *
70     * @return void
71     */
72    public static function run(): void
73    {
74        $document = new \Dom\Document();
75        $parent = $document->createElement('parent');
76        $child = $document->createElement('child');
77        $grandchild = $document->createElement('grandchild');
78        $sibling = $document->createElement('sibling');
79
80        // DOMツリーを構築: parent -> child -> grandchild
81        //              document -> parent, sibling
82        $child->appendChild($grandchild);
83        $parent->appendChild($child);
84        $document->appendChild($parent);
85        $document->appendChild($sibling); // parent と sibling は同じレベルの子要素
86
87        $checker = new self();
88
89        echo "--- シナリオ 1: 親が子を含むか？ ---\n";
90        $checker->checkContains($parent, $child); // 結果: 含む (true)
91
92        echo "\n--- シナリオ 2: 子が親を含むか？ ---\n";
93        $checker->checkContains($child, $parent); // 結果: 含まない (false)
94
95        echo "\n--- シナリオ 3: 親が孫を含むか？ ---\n";
96        $checker->checkContains($parent, $grandchild); // 結果: 含む (true)
97
98        echo "\n--- シナリオ 4: 兄弟関係にあるノードは含むか？ ---\n";
99        $checker->checkContains($parent, $sibling); // 結果: 含まない (false)
100    }
101}
102
103// サンプルコードを実行します。
104DocumentPositionChecker::run();

このサンプルコードは、PHPのDOM拡張機能でノード間の位置関係を比較する際に利用する定数 DOCUMENT_POSITION_CONTAINS について解説しています。リファレンス情報では Dom\Entity クラスに所属するとされていますが、実際のPHPのDOM拡張では Dom\Node クラスの定数 Dom\Node::DOCUMENT_POSITION_CONTAINS として提供されており、ノードが別のノードを内包しているか（親ノードや祖先ノードであるか）を示すビットマスク（整数の値）です。

この定数自体には引数はなく、戻り値は整数型のビットマスクです。利用する際は、Dom\Node::compareDocumentPosition メソッドの戻り値と、ビットAND演算子 & を組み合わせて、特定のノードが別のノードを本当に含んでいるかを判定します。例えば、$node1->compareDocumentPosition($node2) & Dom\Node::DOCUMENT_POSITION_CONTAINS の結果が真であれば、$node1が$node2を内包していると判断できます。

サンプルコードでは、Dom\Entity クラスを模範として定義し、PHPDocコメントで定数の記述例を示しつつ、DocumentPositionChecker クラスで具体的なDOMツリーを構築し、Dom\Node::compareDocumentPosition メソッドと組み込みの Dom\Node::DOCUMENT_POSITION_CONTAINS 定数を使って、ノードの包含関係をチェックする実践的な方法を紹介しています。これにより、DOMノード間の親子関係や祖先関係をプログラムで効率的に判別できるようになります。