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

Copy
1<?php
2
3/**
4 * PHP 8 の Dom\Node クラスに定義されている
5 * DOCUMENT_POSITION_CONTAINED_BY および DOCUMENT_POSITION_PRECEDING 定数を使用して、
6 * 異なるDOMノード間の相対的な位置関係を比較する例です。
7 *
8 * Dom\Node::compareDocumentPosition() メソッドは、比較対象のノードが
9 * 現在のノードに対してどのような位置にあるかを示すビットマスクを整数で返します。
10 */
11function demonstrateNodePositionComparison(): void
12{
13    // HTMLドキュメントを作成し、ノードツリーを構築します。
14    $document = new Dom\Document();
15    // loadHTMLでHTML構造をロードします。
16    $document->loadHTML('
17        <root>
18            <container>
19                <item_a></item_a>
20                <item_b></item_b>
21            </container>
22            <outside_item></outside_item>
23        </root>
24    ');
25
26    // 比較するノードを名前で取得します。
27    // getElementsByTagName() は Dom\HTMLCollection オブジェクトを返すため、item(0) で最初の要素を取得します。
28    $containerNode = $document->getElementsByTagName('container')->item(0);
29    $itemANode = $document->getElementsByTagName('item_a')->item(0);
30    $itemBNode = $document->getElementsByTagName('item_b')->item(0);
31    $outsideItemNode = $document->getElementsByTagName('outside_item')->item(0);
32
33    // ノードが取得できたかを確認します。
34    if (!$containerNode || !$itemANode || !$itemBNode || !$outsideItemNode) {
35        echo "テスト用のHTMLノードの取得に失敗しました。スクリプトを終了します。\n";
36        return;
37    }
38
39    echo "--- DOMノード間の位置関係の比較 --- \n\n";
40
41    /**
42     * 2つのノード間の位置関係を比較し、結果を分かりやすく出力するヘルパー関数。
43     * @param Dom\Node $node1 比較の基準となるノード
44     * @param Dom\Node $node2 比較対象のノード
45     * @param string $name1 node1 の説明的な名前
46     * @param string $name2 node2 の説明的な名前
47     */
48    $analyzePosition = function (Dom\Node $node1, Dom\Node $node2, string $name1, string $name2): void {
49        echo "比較: '{$name1}' と '{$name2}'\n";
50        // compareDocumentPosition() は、node2 から見た node1 の相対位置を返します。
51        $positionFlags = $node1->compareDocumentPosition($node2);
52        echo "  結果フラグ (ビットマスク): {$positionFlags}\n";
53
54        // DOCUMENT_POSITION_CONTAINED_BY のチェック
55        // node1 が node2 に含まれている場合に設定されます。
56        if (($positionFlags & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) !== 0) {
57            echo "  - '{$name1}' は '{$name2}' に含まれています。\n";
58        }
59
60        // DOCUMENT_POSITION_CONTAINS のチェック
61        // node1 が node2 を含んでいる場合に設定されます。
62        if (($positionFlags & Dom\Node::DOCUMENT_POSITION_CONTAINS) !== 0) {
63            echo "  - '{$name1}' は '{$name2}' を含んでいます。\n";
64        }
65
66        // DOCUMENT_POSITION_PRECEDING のチェック
67        // node1 が node2 よりドキュメントの順序で前に来る場合に設定されます。
68        if (($positionFlags & Dom\Node::DOCUMENT_POSITION_PRECEDING) !== 0) {
69            echo "  - '{$name1}' は '{$name2}' より前にあります。\n";
70        }
71
72        // DOCUMENT_POSITION_FOLLOWING のチェック
73        // node1 が node2 よりドキュメントの順序で後に来る場合に設定されます。
74        if (($positionFlags & Dom\Node::DOCUMENT_POSITION_FOLLOWING) !== 0) {
75            echo "  - '{$name1}' は '{$name2}' より後にあります。\n";
76        }
77
78        // DOCUMENT_POSITION_DISCONNECTED のチェック
79        // node1 と node2 が同じドキュメントツリー内にない場合に設定されます。
80        if (($positionFlags & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) !== 0) {
81            echo "  - '{$name1}' と '{$name2}' は異なるサブツリーにあります (またはどちらか一方がドキュメントにない)。\n";
82        }
83
84        // DOCUMENT_POSITION_SAME_NODE のチェック
85        // node1 と node2 が同じノードである場合に設定されます。
86        if ($positionFlags === Dom\Node::DOCUMENT_POSITION_SAME_NODE) {
87            echo "  - '{$name1}' と '{$name2}' は同じノードです。\n";
88        }
89        echo "\n";
90    };
91
92    // ケース1: 親ノードと子ノードの関係
93    // item_a は container の子です。
94    $analyzePosition($itemANode, $containerNode, 'item_a', 'container'); // item_a が container に含まれていることを示す
95
96    // ケース2: 子ノードと親ノードの関係
97    // container は item_a を含んでいます。
98    $analyzePosition($containerNode, $itemANode, 'container', 'item_a'); // container が item_a を含んでいることを示す
99
100    // ケース3: 兄弟ノードの関係
101    // item_a は item_b より前にあります。
102    $analyzePosition($itemANode, $itemBNode, 'item_a', 'item_b'); // item_a が item_b より前に来ることを示す
103
104    // ケース4: 異なる階層にあるがドキュメント順序で前に来るノード
105    // container は outside_item より前にあります。
106    $analyzePosition($containerNode, $outsideItemNode, 'container', 'outside_item'); // container が outside_item より前に来ることを示す
107
108    // ケース5: 異なる階層にあるがドキュメント順序で後に来るノード
109    // outside_item は container より後にあります。
110    $analyzePosition($outsideItemNode, $containerNode, 'outside_item', 'container'); // outside_item が container より後に来ることを示す
111}
112
113// サンプル関数を実行します。
114demonstrateNodePositionComparison();

PHP 8で利用できるDom\NodeクラスのcompareDocumentPosition()メソッドは、二つのDOMノード間の相対的な位置関係を整数値（ビットマスク）で返します。この戻り値の整数値は、複数の定数を組み合わせたもので、各定数が特定の位置関係を示します。

特に、Dom\Node::DOCUMENT_POSITION_CONTAINED_BY定数は、比較の基準となるノードが、比較対象のノードの内部に含まれている場合に、結果のビットマスクに設定されます。たとえば、親ノードと子ノードの関係を比較する際に、子ノードが親ノードに含まれているかどうかを判断できます。

また、キーワードとして指定されたDom\Node::DOCUMENT_POSITION_PRECEDING定数は、比較の基準となるノードが、比較対象のノードよりもドキュメントツリーの順序で物理的に前に位置する場合に、結果のビットマスクに設定されます。これは、兄弟ノード間や異なる階層のノード間で、どちらが先に現れるかを知る際に利用されます。

サンプルコードでは、Dom\Documentで構築されたHTML要素を用いて、さまざまなノード間のcompareDocumentPosition()メソッドの結果を評価しています。具体的には、このメソッドが返す整数値を&演算子で各定数と比較することで、親子の包含関係やドキュメント内での前後の順序関係を判別し、その結果を出力しています。これにより、プログラマはDOMツリー内の要素の相対的な配置を正確に把握し、プログラムで利用することが可能となります。

Copy
1<?php
2
3/**
4 * Dom\Node::DOCUMENT_POSITION_CONTAINED_BY 定数を使用して、DOMノード間の位置関係を比較するサンプルです。
5 * この定数は、あるノードが別のノードに含まれているかどうかを判断する際に使用されます。
6 */
7function demonstrateDocumentPositionComparison(): void
8{
9    // 新しいDOMドキュメントを作成し、簡単なHTMLコンテンツをロードします。
10    $dom = new Dom\Document();
11    $dom->loadHTML('
12        <html>
13        <body>
14            <div id="parent">
15                <p id="child">Child paragraph.</p>
16            </div>
17            <span id="unrelated">Unrelated span.</span>
18        </body>
19        </html>
20    ');
21
22    // XPathを使用して、比較するノードを取得します。
23    $xpath = new Dom\XPath($dom);
24    $parentNode = $xpath->query('//div[@id="parent"]')->item(0);
25    $childNode = $xpath->query('//p[@id="child"]')->item(0);
26    $unrelatedNode = $xpath->query('//span[@id="unrelated"]')->item(0);
27
28    // ノードが正しく取得できたか確認します。
29    if (!$parentNode || !$childNode || !$unrelatedNode) {
30        echo "エラー: 比較に必要なノードが見つかりませんでした。\n";
31        return;
32    }
33
34    echo "--- 親ノード ('parent') と子ノード ('child') の比較 ---\n";
35    // parentNodeを基準としてchildNodeの位置を比較します。
36    // 戻り値はビットマスクであり、複数の状態を示すフラグの組み合わせです。
37    $positionFlags = $parentNode->compareDocumentPosition($childNode);
38
39    // Dom\Node::DOCUMENT_POSITION_CONTAINED_BY は、比較対象ノードが基準ノードに含まれていることを示します。
40    // この場合、$childNodeは$parentNodeに含まれているため、この条件が真になります。
41    if (($positionFlags & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
42        echo "結果: 'child' ノードは 'parent' ノードに含まれています。\n";
43    } else {
44        echo "結果: 'child' ノードは 'parent' ノードに含まれていません。\n";
45    }
46
47    // Dom\Node::DOCUMENT_POSITION_CONTAINS は、基準ノードが比較対象ノードを含んでいることを示します。
48    // この場合、$parentNodeは$childNodeを含んでいるため、この条件も真になります。
49    if (($positionFlags & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
50        echo "補足: 'parent' ノードは 'child' ノードを含んでいます。\n";
51    }
52
53    echo "\n--- 親ノード ('parent') と無関係なノード ('unrelated') の比較 ---\n";
54    // parentNodeを基準としてunrelatedNodeの位置を比較します。
55    // unrelatedNodeはparentNodeに含まれていません。
56    $positionFlags = $parentNode->compareDocumentPosition($unrelatedNode);
57
58    // $unrelatedNodeは$parentNodeに含まれていないため、この条件は偽になります。
59    if (($positionFlags & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
60        echo "結果: 'unrelated' ノードは 'parent' ノードに含まれています。\n";
61    } else {
62        echo "結果: 'unrelated' ノードは 'parent' ノードに含まれていません。\n";
63    }
64
65    // Dom\Node::DOCUMENT_POSITION_DISCONNECTED は、2つのノードがDOMツリー内で接続されていないことを示します。
66    // この場合、$parentNodeと$unrelatedNodeは親子関係にないため、この条件が真になります。
67    if (($positionFlags & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) === Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
68        echo "補足: 'parent' ノードと 'unrelated' ノードは接続されていません。\n";
69    }
70}
71
72// 定義した関数を実行します。
73demonstrateDocumentPositionComparison();

このサンプルコードは、PHPのDOM拡張機能を利用して、HTMLドキュメント内のノード同士の位置関係を比較する方法を示しています。特に、Dom\Node::DOCUMENT_POSITION_CONTAINED_BY定数の利用例を通して、あるノードが別のノードの中に含まれているかどうかを判断する仕組みを解説します。

コードではまず、簡単なHTML構造を持つDOMドキュメントを作成し、親ノード、子ノード、および無関係なノードを取得します。次に、Dom\NodeクラスのcompareDocumentPosition()メソッドを使用してノード間の位置を比較します。このメソッドは比較したいノードを引数にとり、ノード間の複数の関係を示す整数値（ビットマスク）を戻り値として返します。

Dom\Node::DOCUMENT_POSITION_CONTAINED_BY定数は、compareDocumentPosition()の戻り値に、比較対象のノードが基準となるノードの内部に含まれているという情報が含まれているかどうかを判断するために使用されます。サンプルでは、親ノードと子ノードを比較し、子ノードが親ノードに含まれている場合に、この定数を用いてその事実を正確に判定できることを示しています。

また、関連する定数として、基準ノードが比較対象ノードを含んでいることを示すDOCUMENT_POSITION_CONTAINSや、二つのノードがDOMツリー内で接続されていないことを示すDOCUMENT_POSITION_DISCONNECTEDも登場します。これらの定数をビット演算子で組み合わせることで、複雑なDOM構造におけるノード間の様々な位置関係を、プログラムで詳細に分析することが可能になります。この機能は、HTMLやXMLドキュメントの構造を理解し、操作する上で非常に重要です。