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

Copy
1<?php
2
3/**
4 * Demonstrates the use of Dom\Entity::DOCUMENT_POSITION_FOLLOWING and
5 * Dom\Entity::DOCUMENT_POSITION_PRECEDING constants.
6 *
7 * These constants are integer values used to interpret the bitmask
8 * returned by Node::compareDocumentPosition(), which determines the relative
9 * position of two nodes within a document.
10 */
11function demonstrateDocumentPositionConstants(): void
12{
13    // 1. Create a new DOMDocument instance.
14    // This object represents an entire HTML or XML document.
15    $dom = new DOMDocument();
16
17    // 2. Load a simple HTML string into the DOMDocument.
18    // The `loadHTML` method parses the string into a DOM structure.
19    $html = '<div><p id="para1">First paragraph</p><span id="span1">Second element</span></div>';
20    $dom->loadHTML($html);
21
22    // 3. Get references to specific nodes within the document.
23    // For simplicity, we get them by tag name and their index in the collection.
24    $div = $dom->getElementsByTagName('div')->item(0);
25    $p = $dom->getElementsByTagName('p')->item(0);
26    $span = $dom->getElementsByTagName('span')->item(0);
27
28    // Basic check to ensure required nodes were found.
29    if (!$div || !$p || !$span) {
30        echo "Error: Could not find required elements in the DOM. Ensure HTML is valid.\n";
31        return;
32    }
33
34    echo "--- Demonstrating DOM Node Position Comparison ---\n\n";
35
36    // Display the integer values of relevant position constants for clarity.
37    echo "Relevant DOM Node Position Constants (integer values):\n";
38    echo "  - DOCUMENT_POSITION_PRECEDING:  " . Dom\Entity::DOCUMENT_POSITION_PRECEDING . " (Node B precedes Node A)\n";
39    echo "  - DOCUMENT_POSITION_FOLLOWING:  " . Dom\Entity::DOCUMENT_POSITION_FOLLOWING . " (Node B follows Node A)\n";
40    echo "  - DOCUMENT_POSITION_CONTAINS:   " . Dom\Entity::DOCUMENT_POSITION_CONTAINS . " (Node B contains Node A)\n";
41    echo "  - DOCUMENT_POSITION_CONTAINED_BY: " . Dom\Entity::DOCUMENT_POSITION_CONTAINED_BY . " (Node B is contained by Node A)\n\n";
42
43
44    // Scenario 1: A node ('p') preceding another node ('span')
45    // The 'p' node appears before the 'span' node in the document order.
46    echo "1. Comparing 'p' node (id='para1') to 'span' node (id='span1'):\n";
47    $position = $p->compareDocumentPosition($span);
48    echo "   Resulting bitmask: " . $position . "\n";
49
50    // Use bitwise AND (&) to check if a specific flag is set in the returned bitmask.
51    if (($position & Dom\Entity::DOCUMENT_POSITION_PRECEDING) === Dom\Entity::DOCUMENT_POSITION_PRECEDING) {
52        echo "   -> The 'p' node PRECEDES the 'span' node.\n";
53    }
54    echo "\n";
55
56
57    // Scenario 2: A node ('span') following another node ('p')
58    // The 'span' node appears after the 'p' node in the document order.
59    echo "2. Comparing 'span' node (id='span1') to 'p' node (id='para1'):\n";
60    $position = $span->compareDocumentPosition($p);
61    echo "   Resulting bitmask: " . $position . "\n";
62
63    if (($position & Dom\Entity::DOCUMENT_POSITION_FOLLOWING) === Dom\Entity::DOCUMENT_POSITION_FOLLOWING) {
64        echo "   -> The 'span' node FOLLOWS the 'p' node.\n";
65    }
66    echo "\n";
67
68
69    // Scenario 3: Child node ('p') compared to its Parent node ('div')
70    // A child node is "contained by" its parent, and also "follows" it in document order (after parent's start tag).
71    echo "3. Comparing 'p' node (child) to 'div' node (parent):\n";
72    $position = $p->compareDocumentPosition($div);
73    echo "   Resulting bitmask: " . $position . "\n";
74
75    if (($position & Dom\Entity::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Entity::DOCUMENT_POSITION_CONTAINED_BY) {
76        echo "   -> The 'p' node is CONTAINED_BY the 'div' node.\n";
77    }
78    if (($position & Dom\Entity::DOCUMENT_POSITION_FOLLOWING) === Dom\Entity::DOCUMENT_POSITION_FOLLOWING) {
79        echo "   -> The 'p' node also FOLLOWS the 'div' node in document order.\n";
80    }
81    echo "\n";
82
83    // Scenario 4: Parent node ('div') compared to its Child node ('p')
84    // A parent node "contains" its child, and also "precedes" it in document order (before child's start tag).
85    echo "4. Comparing 'div' node (parent) to 'p' node (child):\n";
86    $position = $div->compareDocumentPosition($p);
87    echo "   Resulting bitmask: " . $position . "\n";
88
89    if (($position & Dom\Entity::DOCUMENT_POSITION_CONTAINS) === Dom\Entity::DOCUMENT_POSITION_CONTAINS) {
90        echo "   -> The 'div' node CONTAINS the 'p' node.\n";
91    }
92    if (($position & Dom\Entity::DOCUMENT_POSITION_PRECEDING) === Dom\Entity::DOCUMENT_POSITION_PRECEDING) {
93        echo "   -> The 'div' node also PRECEDES the 'p' node in document order.\n";
94    }
95    echo "\n";
96
97    echo "--- End of Demonstration ---\n";
98}
99
100// Execute the demonstration function when the script runs.
101demonstrateDocumentPositionConstants();
102

Dom\Entity::DOCUMENT_POSITION_FOLLOWING は、PHP 8で提供されるDOM拡張機能に属する定数で、HTMLやXMLドキュメント内で2つのノードがどのような位置関係にあるかを示すための整数値です。この定数に引数はなく、特定の状況を示す数値そのものとなります。

主に Node::compareDocumentPosition() メソッドの戻り値と組み合わせて使用されます。compareDocumentPosition() は2つのノードの相対的な位置関係をビットマスク（複数の状態を組み合わせた数値）で返し、そのビットマスクを Dom\Entity::DOCUMENT_POSITION_FOLLOWING やキーワードにある Dom\Entity::DOCUMENT_POSITION_PRECEDING などの定数とビット演算子 (&) を使って比較することで、詳細な位置関係を判定します。

具体的に DOCUMENT_POSITION_FOLLOWING は、比較対象のノードが基準となるノードの「後に続く」位置にある場合に該当することを示します。例えば、同じ階層で先に現れる段落ノードと後に現れるスパンノードを比較する場合、スパンノードから段落ノードを見ると、スパンノードは段落ノードの後に続いていると判定されます。対照的に DOCUMENT_POSITION_PRECEDING は、比較対象のノードが基準ノードの「前に存在する」位置にある場合を示します。

サンプルコードでは、まずHTML文字列を読み込み、複数のノードを取得しています。その後、それぞれのノードを compareDocumentPosition() で比較し、返されたビットマスクと DOCUMENT_POSITION_FOLLOWING や DOCUMENT_POSITION_PRECEDING などの定数を論理積 (&) でチェックすることで、ノードの前後関係や親子関係（包含関係）を判別する具体的な方法が示されています。これにより、ドキュメントツリー内の複雑なノードの位置関係をプログラムで正確に把握し、処理に役立てることが可能です。

Copy
1<?php
2
3/**
4 * HTTP POSTリクエストからXMLデータを受け取り、DOMノードの位置を比較する関数。
5 *
6 * この関数はPOSTされたXML文字列を処理し、DOMドキュメント内の2つの特定ノードの位置を比較します。
7 * ノードが「後続している」かどうかを判定するために、ドキュメント位置定数の整数値を使用します。
8 *
9 * リファレンス情報では「Dom\Entity::DOCUMENT_POSITION_FOLLOWING」と指定されていますが、
10 * PHP 8の公式ドキュメントにおいてこの定数は`Dom\Entity`クラスでは確認できません。
11 * 代わりに、DOMノードの比較で一般的に使用される`DOMNode::DOCUMENT_POSITION_FOLLOWING`の
12 * 整数値 `2` を使用して比較を行います。これは、リファレンス情報が返す型を `int` としているため、
13 * その値を使って動作を実演するものです。
14 *
15 * @param string $xmlData POSTリクエストで受け取ったXML文字列。
16 * @return string ノードの位置比較の結果を示すメッセージ。
17 */
18function compareDomNodePositions(string $xmlData): string
19{
20    // DOMDocumentのインスタンスを作成し、XMLをロード
21    $dom = new DOMDocument();
22    $dom->preserveWhiteSpace = false; // 空白ノードを無視
23    $dom->formatOutput = true;      // 整形出力
24
25    if (!$dom->loadXML($xmlData)) {
26        return "エラー: XMLデータのロードに失敗しました。有効なXMLを提供してください。";
27    }
28
29    $root = $dom->documentElement;
30    if (!$root) {
31        return "エラー: XML内にルート要素が見つかりません。";
32    }
33
34    // 比較対象のノードを取得
35    // 例として、ルートの最初と2番目の要素ノードを取得します。
36    $nodeA = null;
37    $nodeB = null;
38
39    $elementNodes = [];
40    foreach ($root->childNodes as $child) {
41        if ($child->nodeType === XML_ELEMENT_NODE) {
42            $elementNodes[] = $child;
43        }
44    }
45
46    if (count($elementNodes) >= 2) {
47        $nodeA = $elementNodes[0];
48        $nodeB = $elementNodes[1];
49    } elseif (count($elementNodes) === 1 && $elementNodes[0]->hasChildNodes()) {
50        // ルート直下に要素が1つの場合、その最初の子孫から2つの要素を探す
51        $grandChildren = [];
52        foreach ($elementNodes[0]->childNodes as $grandChild) {
53            if ($grandChild->nodeType === XML_ELEMENT_NODE) {
54                $grandChildren[] = $grandChild;
55            }
56        }
57        if (count($grandChildren) >= 2) {
58            $nodeA = $grandChildren[0];
59            $nodeB = $grandChildren[1];
60        }
61    }
62
63    if (!$nodeA || !$nodeB) {
64        return "エラー: 提供されたXMLで比較可能な2つ以上の要素ノードが見つかりませんでした。";
65    }
66
67    // DOMNode::compareDocumentPosition() メソッドを使用してノードの位置を比較
68    // 結果はビットマスクとして返されます。
69    $position = $nodeA->compareDocumentPosition($nodeB);
70
71    $resultMessage = "ノード '{$nodeA->nodeName}' と '{$nodeB->nodeName}' の比較: ";
72
73    // リファレンス情報にあるDom\Entity::DOCUMENT_POSITION_FOLLOWINGはintを返すとされているため、
74    // DOMNode::DOCUMENT_POSITION_FOLLOWINGの整数値（2）を直接使用します。
75    // この値はノードが他のノードの後に続くことを示します。
76    $followingValue = 2; // DOMNode::DOCUMENT_POSITION_FOLLOWING の整数値
77
78    if (($position & $followingValue) === $followingValue) {
79        $resultMessage .= "'{$nodeB->nodeName}' は '{$nodeA->nodeName}' の後に続きます。";
80    } else {
81        $resultMessage .= "'{$nodeB->nodeName}' は '{$nodeA->nodeName}' の後に続きません。";
82    }
83
84    return $resultMessage;
85}
86
87// --------------------------------------------------------------------------------
88// スクリプトのエントリポイント：HTTP POSTリクエストの処理
89// --------------------------------------------------------------------------------
90
91if ($_SERVER['REQUEST_METHOD'] === 'POST') {
92    // phpdocでPOSTリクエストのパラメータを説明します。
93    /**
94     * @var string $xmlData POSTリクエストから送られたXML文字列。
95     *                      HTMLフォームの 'xml_data' フィールドに期待されます。
96     *                      これはHTTP POSTリクエストのパラメータ (`$_POST`) のドキュメントとして機能します。
97     * @param array $_POST HTTP POSTリクエストのすべてのデータ。
98     */
99    $xmlData = $_POST['xml_data'] ?? '';
100
101    if (!empty($xmlData)) {
102        // 関数を呼び出し、結果を出力
103        echo compareDomNodePositions($xmlData);
104    } else {
105        echo "エラー: POSTリクエストに 'xml_data' パラメータが見つからないか、空です。";
106    }
107} else {
108    // GETリクエストの場合は、XML入力フォームを表示
109    echo <<<HTML
110<!DOCTYPE html>
111<html lang="ja">
112<head>
113    <meta charset="UTF-8">
114    <meta name="viewport" content="width=device-width, initial-scale=1.0">
115    <title>DOMノード位置比較の例 (PHP 8)</title>
116    <style>
117        body { font-family: sans-serif; margin: 20px; line-height: 1.6; }
118        textarea { width: 80%; max-width: 600px; height: 150px; margin-bottom: 10px; padding: 10px; border: 1px solid #ccc; border-radius: 4px; }
119        input[type="submit"] { padding: 10px 20px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; font-size: 16px; }
120        input[type="submit"]:hover { background-color: #0056b3; }
121        h1 { color: #333; }
122        p { color: #666; }
123        label { display: block; margin-bottom: 5px; font-weight: bold; color: #333; }
124        form { margin-top: 20px; padding: 20px; border: 1px solid #eee; border-radius: 8px; background-color: #f9f9f9; }
125    </style>
126</head>
127<body>
128    <h1>DOMノード位置比較の例 (PHP 8)</h1>
129    <p>
130        この例では、PHPのDOM拡張機能を使用して2つのDOM要素の位置を比較する方法を示します。<br>
131        HTTP POSTリクエストで送信されたXMLデータを処理し、ある要素がドキュメント構造内で別の要素の
132        <span style="font-weight: bold;">「後に続いている」</span>かどうかをチェックします。
133    </p>
134    <p>
135        リファレンス情報で指定された `Dom\\Entity::DOCUMENT_POSITION_FOLLOWING` は `int` を返す定数です。<br>
136        PHP 8の公式ドキュメントでは`Dom\\Entity`クラスにこの定数は明示されていませんが、
137        `DOMNode::DOCUMENT_POSITION_FOLLOWING`（整数値 `2`）が同様の目的で利用されます。
138        このサンプルコードでは、この一般的な整数値を使用して、ドキュメント位置の比較を実演します。
139    </p>
140    <form method="POST" action="">
141        <label for="xml_data">XMLデータを入力してください:</label><br>
142        <textarea id="xml_data" name="xml_data">&lt;root&gt;
143    &lt;childA id="a1"/&gt;
144    &lt;childB id="b1"/&gt;
145&lt;/root&gt;</textarea><br>
146        <input type="submit" value="DOM位置を比較">
147    </form>
148</body>
149</html>
150HTML;
151}

このPHPサンプルコードは、HTTP POSTリクエストを通じて受け取ったXMLデータを利用し、DOM（Document Object Model）ツリー内の2つのノードが相対的にどのような位置関係にあるかを比較する方法を初心者向けに示しています。コードはまず、受け取ったXML文字列を DOMDocument クラスで解析し、DOMドキュメントを作成します。次に、このドキュメントから2つの要素ノードを抽出し、DOMNode::compareDocumentPosition() メソッドを用いてそれらの位置を比較します。

リファレンス情報にある Dom\Entity::DOCUMENT_POSITION_FOLLOWING 定数はPHP 8の公式ドキュメントで直接確認できませんが、戻り値が整数（int）であるため、このコードではDOMノードの比較で一般的に利用される DOMNode::DOCUMENT_POSITION_FOLLOWING の整数値「2」を用いて、一方のノードがもう一方のノードの「後に続いている」かどうかを判定する様子を実演しています。

compareDomNodePositions 関数は、@param タグで示されるように、POSTリクエストで渡されるXML文字列 $xmlData を引数として受け取ります。そして、ノードの比較結果を説明する文字列を return します。コード内では phpdoc 形式のコメントで関数の説明や、$_POST から取得する xml_data パラメータに関する情報が記述されており、システムエンジニアを目指す方がコードを理解しやすいように配慮されています。有効なXMLデータが提供されない場合や比較可能なノードが見つからない場合には、適切なエラーメッセージが返されます。