【PHP8.x】DOMDocument::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドを使用して、
5 * ノード間の位置関係を比較するサンプルコードです。
6 *
7 * DOM_DOCUMENT_POSITION_PRECEDING および DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
8 * の定数の使われ方を具体的に示します。
9 *
10 * @link https://www.php.net/manual/ja/class.domnode.php#domnode.constants.compare-document-position
11 */
12function demonstrateDocumentPositionComparison(): void
13{
14    // DOMDocumentオブジェクトを作成し、HTMLコンテンツをロードします。
15    // PHP 8ではDOMDocument::loadHTML()でエラーが発生した場合に
16    // 警告が出力されることがあるため、libxml_use_internal_errors()で抑制します。
17    $dom = new DOMDocument();
18    libxml_use_internal_errors(true);
19    $html = '
20    <div>
21        <p id="firstP">最初の段落です。</p>
22        <span id="spanElement">これはスパン要素です。</span>
23        <p id="secondP">2番目の段落です。</p>
24    </div>';
25    $dom->loadHTML($html);
26    libxml_clear_errors(); // エラーをクリアし、正常な処理を継続
27
28    // 比較対象となるノードをIDから取得します。
29    $firstP = $dom->getElementById('firstP');
30    $spanElement = $dom->getElementById('spanElement'); // この例では使用しませんが、存在を示す
31    $secondP = $dom->getElementById('secondP');
32    $divElement = $dom->getElementsByTagName('div')->item(0);
33
34    echo "--- DOMノードの位置関係の比較 ---" . PHP_EOL;
35    echo "DOMNode::compareDocumentPosition() の戻り値は複数のビットマスクの組み合わせです。" . PHP_EOL;
36    echo "主な定数の意味:" . PHP_EOL;
37    echo " - DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): ノードが別のDOMツリーにあるか、接続されていません。" . PHP_EOL;
38    echo " - DOM_DOCUMENT_POSITION_PRECEDING (0x02): 比較対象ノード (\$other) が現在のノード (this) の前に来ます。" . PHP_EOL;
39    echo " - DOM_DOCUMENT_POSITION_FOLLOWING (0x04): 比較対象ノード (\$other) が現在のノード (this) の後に来ます。" . PHP_EOL;
40    echo " - DOM_DOCUMENT_POSITION_CONTAINS (0x08): 現在のノード (this) が比較対象ノード (\$other) を含みます。" . PHP_EOL;
41    echo " - DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): 現在のノード (this) が比較対象ノード (\$other) に含まれます。" . PHP_EOL;
42    echo " - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装固有の情報を表すビットです。" . PHP_EOL;
43
44
45    // 例1: 兄弟ノードの比較 (secondP と firstP)
46    // firstPはsecondPよりDOMツリー順で「前」に位置します。
47    if ($secondP && $firstP) {
48        echo PHP_EOL . "◆ secondP と firstP を比較します (secondP->compareDocumentPosition(firstP))" . PHP_EOL;
49        $position = $secondP->compareDocumentPosition($firstP);
50        echo "  戻り値 (整数): " . $position . PHP_EOL;
51
52        // DOM_DOCUMENT_POSITION_PRECEDING のチェック
53        // secondPの視点から見て、firstPはDOMツリー順で「前に来る」ため、このフラグが立ちます。
54        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
55            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: TRUE (firstPはsecondPに先行します)" . PHP_EOL;
56        } else {
57            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: FALSE" . PHP_EOL;
58        }
59        // DOM_DOCUMENT_POSITION_FOLLOWING のチェック
60        // firstPはsecondPより「後に来る」わけではないため、このフラグは立ちません。
61        if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
62            echo "  - DOM_DOCUMENT_POSITION_FOLLOWING: TRUE (firstPはsecondPの後に来ます)" . PHP_EOL;
63        } else {
64            echo "  - DOM_DOCUMENT_POSITION_FOLLOWING: FALSE" . PHP_EOL;
65        }
66        // DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC のチェック (リファレンス情報に指定された定数)
67        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
68            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: TRUE (実装固有のビットが設定されています)" . PHP_EOL;
69        } else {
70            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: FALSE" . PHP_EOL;
71        }
72    }
73
74    // 例2: 兄弟ノードの比較 (firstP と secondP)
75    // secondPはfirstPよりDOMツリー順で「後」に位置します。
76    if ($firstP && $secondP) {
77        echo PHP_EOL . "◆ firstP と secondP を比較します (firstP->compareDocumentPosition(secondP))" . PHP_EOL;
78        $position = $firstP->compareDocumentPosition($secondP);
79        echo "  戻り値 (整数): " . $position . PHP_EOL;
80
81        // DOM_DOCUMENT_POSITION_PRECEDING のチェック
82        // firstPの視点から見て、secondPはDOMツリー順で「前に来る」わけではないため、このフラグは立ちません。
83        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
84            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: TRUE (secondPはfirstPに先行します)" . PHP_EOL;
85        } else {
86            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: FALSE" . PHP_EOL;
87        }
88        // DOM_DOCUMENT_POSITION_FOLLOWING のチェック
89        // firstPの視点から見て、secondPはDOMツリー順で「後に来る」ため、このフラグが立ちます。
90        if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
91            echo "  - DOM_DOCUMENT_POSITION_FOLLOWING: TRUE (secondPはfirstPの後に来ます)" . PHP_EOL;
92        } else {
93            echo "  - DOM_DOCUMENT_POSITION_FOLLOWING: FALSE" . PHP_EOL;
94        }
95        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
96            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: TRUE (実装固有のビットが設定されています)" . PHP_EOL;
97        } else {
98            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: FALSE" . PHP_EOL;
99        }
100    }
101
102    // 例3: 親子ノードの比較 (firstP と divElement)
103    // divElementはfirstPを「含み」、firstPよりDOMツリー順で「前」に位置します。
104    if ($firstP && $divElement) {
105        echo PHP_EOL . "◆ firstP と divElement を比較します (firstP->compareDocumentPosition(divElement))" . PHP_EOL;
106        $position = $firstP->compareDocumentPosition($divElement);
107        echo "  戻り値 (整数): " . $position . PHP_EOL;
108
109        // DOM_DOCUMENT_POSITION_CONTAINED_BY のチェック
110        // firstPはdivElementに「内包されている」ため、このフラグが立ちます。
111        if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
112            echo "  - DOM_DOCUMENT_POSITION_CONTAINED_BY: TRUE (firstPはdivElementに内包されています)" . PHP_EOL;
113        } else {
114            echo "  - DOM_DOCUMENT_POSITION_CONTAINED_BY: FALSE" . PHP_EOL;
115        }
116        // DOM_DOCUMENT_POSITION_PRECEDING のチェック
117        // firstPの視点から見て、divElementはDOMツリー順で「前に来る」ため、このフラグが立ちます。
118        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
119            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: TRUE (divElementはfirstPに先行します)" . PHP_EOL;
120        } else {
121            echo "  - DOM_DOCUMENT_POSITION_PRECEDING: FALSE" . PHP_EOL;
122        }
123        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
124            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: TRUE (実装固有のビットが設定されています)" . PHP_EOL;
125        } else {
126            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: FALSE" . PHP_EOL;
127        }
128    }
129}
130
131// 関数を実行してサンプルコードを動作させます。
132demonstrateDocumentPositionComparison();

このサンプルコードは、PHPのDOM機能を利用して、HTML文書内のノード（要素）同士の相対的な位置関係を比較する方法を示しています。具体的には、DOMNode::compareDocumentPosition()メソッドがどのように使用されるかを解説しています。このメソッドは、引数で渡されたノードが現在のノードに対してDOMツリーのどこに位置するかを、複数の状態を示すビットマスクの組み合わせである整数値として返します。

特に、DOM_DOCUMENT_POSITION_PRECEDINGとDOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICの二つの定数がコード内で使われています。DOM_DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが現在のノードよりもDOMツリー順で「前に位置する」場合に設定されるビットを示します。一方、DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICは、DOMの実装に固有の追加情報が存在する場合に設定されるビットマスクであり、他の位置関係のフラグと組み合わせて戻り値に含まれることがあります。

コードは、兄弟ノードや親子ノードの具体的な比較例を通して、これらの定数を含むメソッドの戻り値がどのように解釈され、各ノード間の物理的な位置関係が判別されるかを詳細に説明しています。これにより、WebページのHTML構造をプログラムで正確に把握し、特定の要素の前後関係や包含関係に基づいて処理を行うための基礎的な知識を学ぶことができます。

Copy
1<?php
2
3/**
4 * Represents an interface for comparing the relative position of DOM nodes.
5 *
6 * This interface defines a contract for classes that provide functionality
7 * to describe the relationship between two DOM nodes within a document or across documents.
8 */
9interface NodePositionComparerInterface
10{
11    /**
12     * Compares the position of two DOM nodes and returns a descriptive string
13     * detailing their relationship.
14     *
15     * @param DOMNode $node1 The first DOM node to compare.
16     * @param DOMNode $node2 The second DOM node to compare.
17     * @return string A human-readable description of the node's relative positions.
18     */
19    public function describeNodeRelationship(DOMNode $node1, DOMNode $node2): string;
20}
21
22/**
23 * Implements the NodePositionComparerInterface to provide concrete
24 * functionality for comparing DOM node positions.
25 *
26 * This class uses the DOMNode::compareDocumentPosition method and interprets
27 * its bitmask result, including the DOMDocument::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC constant.
28 *
29 * @implements NodePositionComparerInterface
30 */
31class DomNodePositionDescriber implements NodePositionComparerInterface
32{
33    /**
34     * @inheritDoc
35     */
36    public function describeNodeRelationship(DOMNode $node1, DOMNode $node2): string
37    {
38        // Compare the positions of the two nodes.
39        // This method returns an integer bitmask representing the relationship.
40        $position = $node1->compareDocumentPosition($node2);
41
42        $descriptions = [];
43
44        // Check various flags from the bitmask using bitwise AND (&).
45        // Each flag indicates a specific relationship.
46        if ($position === 0) {
47            $descriptions[] = 'Nodes are the same';
48        }
49        if ($position & DOMDocument::DOCUMENT_POSITION_DISCONNECTED) {
50            $descriptions[] = 'Nodes are disconnected (not in the same tree or document)';
51        }
52        if ($position & DOMDocument::DOCUMENT_POSITION_PRECEDING) {
53            $descriptions[] = 'Node1 precedes Node2 in document order';
54        }
55        if ($position & DOMDocument::DOCUMENT_POSITION_FOLLOWING) {
56            $descriptions[] = 'Node1 follows Node2 in document order';
57        }
58        if ($position & DOMDocument::DOCUMENT_POSITION_CONTAINS) {
59            $descriptions[] = 'Node1 contains Node2';
60        }
61        if ($position & DOMDocument::DOCUMENT_POSITION_CONTAINED_BY) {
62            $descriptions[] = 'Node1 is contained by Node2';
63        }
64        // This constant indicates that the position is implementation-specific.
65        // It often occurs when nodes belong to different documents or have an unusual relationship.
66        if ($position & DOMDocument::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
67            $descriptions[] = 'Position is implementation-specific (e.g., nodes from different document instances)';
68        }
69
70        // Return a concatenated string of all relevant descriptions.
71        return empty($descriptions) ? 'Unknown relationship' : implode('; ', $descriptions);
72    }
73}
74
75// --- Sample Usage ---
76
77// 1. Create a DOM document and some nodes within it.
78$domA = new DOMDocument();
79$domA->loadXML('<root><child1/><child2/></root>');
80
81$child1_a = $domA->getElementsByTagName('child1')->item(0);
82$child2_a = $domA->getElementsByTagName('child2')->item(0);
83$root_a = $domA->getElementsByTagName('root')->item(0);
84
85// 2. Create another DOM document and a node within it.
86$domB = new DOMDocument();
87$domB->loadXML('<other_root><other_child/></other_root>');
88$other_child_b = $domB->getElementsByTagName('other_child')->item(0);
89
90// Instantiate the describer class.
91$describer = new DomNodePositionDescriber();
92
93echo "--- Comparing nodes within the same document (domA) ---\n";
94echo "Child1 vs Child2: " . $describer->describeNodeRelationship($child1_a, $child2_a) . "\n";
95echo "Child2 vs Child1: " . $describer->describeNodeRelationship($child2_a, $child1_a) . "\n";
96echo "Root vs Child1: " . $describer->describeNodeRelationship($root_a, $child1_a) . "\n";
97echo "Child1 vs Root: " . $describer->describeNodeRelationship($child1_a, $root_a) . "\n";
98echo "Child1 vs Child1: " . $describer->describeNodeRelationship($child1_a, $child1_a) . "\n";
99
100echo "\n--- Comparing nodes from different documents ---\n";
101// This comparison is highly likely to trigger DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
102// because the nodes are from completely separate DOM trees.
103echo "Child1 (domA) vs OtherChild (domB): " . $describer->describeNodeRelationship($child1_a, $other_child_b) . "\n";

このサンプルコードは、PHPのDOMDocumentクラスを用いて、HTMLやXML文書内のDOMノード同士の相対的な位置関係を比較し、その結果を説明する仕組みを示しています。

まず、NodePositionComparerInterfaceインターフェースがノード比較機能の共通規約を定義しており、DomNodePositionDescriberクラスがこれを実装しています。DomNodePositionDescriberクラスのdescribeNodeRelationshipメソッドは、2つのDOMNodeオブジェクトを引数に取り、DOMNode::compareDocumentPositionメソッドを使ってノード間の位置を比較します。このメソッドは、ノード間の関係を示す整数値（ビットマスク）を返します。

戻り値の整数値は、DOMDocument::DOCUMENT_POSITION_DISCONNECTEDやDOMDocument::DOCUMENT_POSITION_PRECEDINGといった複数の定数の組み合わせで構成されます。これらの定数の一つにDOMDocument::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICがあります。この定数は、比較しているノードが異なるDOM文書に属している場合など、環境や実装に依存する特殊な位置関係を示すために利用されます。

describeNodeRelationshipメソッドでは、ビット演算子&を用いて、返されたビットマスクと各定数を照合し、「ノードは同じ」「ノード1がノード2を含む」といった人間が読める説明文を生成して返します。サンプルコードの実行例では、同じ文書内のノード比較に加えて、異なる文書に属するノード同士を比較する際に、DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC定数によって「実装固有の」関係が示される様子を確認できます。この機能は、DOM操作においてノードの配置を厳密にチェックする際に役立ちます。