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

Copy
1<?php
2
3// このサンプルコードはPHP 8の標準DOM拡張を使用します。
4// Composerは現代のPHP開発で推奨される依存関係マネージャーですが、
5// このコード自体は特別なライブラリのインストールを必要としません。
6// phpdocumentorスタイルのコメントを用いて、コードの可読性を高めています。
7
8/**
9 * Dom\Notation ノードと他の Dom\Node ノードの相対的な位置を比較し、結果を出力します。
10 *
11 * Dom\Notation はXMLのDTDで定義される「記法」を表し、
12 * 通常のDOMツリーの要素やテキストとは異なるため、位置関係は「Disconnected」となることが多いです。
13 *
14 * @param \Dom\Notation $notationNode 比較対象となる Dom\Notation インスタンス
15 * @param \Dom\Node     $otherNode    比較対象となる任意の Dom\Node インスタンス
16 * @return void
17 */
18function compareDomNodePositions(\Dom\Notation $notationNode, \Dom\Node $otherNode): void
19{
20    echo "--- ノード位置の比較 ---" . PHP_EOL;
21    echo "ノード1 (Notation): '" . ($notationNode->nodeName ?: '不明') . "' (systemId: " . ($notationNode->systemId ?: 'なし') . ")" . PHP_EOL;
22    echo "ノード2 (Other):    '" . ($otherNode->nodeName ?: '不明') . "'" . PHP_EOL;
23
24    // Dom\Notation::compareDocumentPosition() メソッドを呼び出し、位置関係を示すビットマスクを取得
25    $position = $notationNode->compareDocumentPosition($otherNode);
26
27    echo "結果のビットマスク値: " . sprintf("0x%02X", $position) . PHP_EOL;
28
29    // 戻り値を Dom\Node クラスの定数（ビットマスク）と比較して、ノード間の関係を解釈します。
30    // 複数の関係が同時に成り立つことがあるため、ビット論理積 (&) を使用します。
31
32    if ($position === 0) {
33        echo "  - 0x00: 何も関係が検出されませんでした（通常、これは発生しません）。" . PHP_EOL;
34    }
35
36    if ($position & \Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
37        echo "  - [0x01] Disconnected: ノードが同じドキュメントツリー内にないか、ツリー内だが直接的な階層関係（親子・兄弟）がない。" . PHP_EOL;
38    }
39    if ($position & \Dom\Node::DOCUMENT_POSITION_PRECEDING) {
40        echo "  - [0x02] Preceding: otherNode が notationNode の前に位置する。" . PHP_EOL;
41    }
42    if ($position & \Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
43        echo "  - [0x04] Following: otherNode が notationNode の後に位置する。" . PHP_EOL;
44    }
45    if ($position & \Dom\Node::DOCUMENT_POSITION_CONTAINS) {
46        echo "  - [0x08] Contains: notationNode が otherNode を内包している（notationNode が otherNode の祖先である）。" . PHP_EOL;
47    }
48    if ($position & \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
49        echo "  - [0x10] Contained By: notationNode が otherNode に内包されている（notationNode が otherNode の子孫である）。" . PHP_EOL;
50    }
51    if ($position & \Dom\Node::DOCUMENT_POSITION_SAME_NODE) {
52        echo "  - [0x20] Same Node: 両方のノードが同じノードを参照している。" . PHP_EOL;
53    }
54
55    echo PHP_EOL;
56}
57
58// -----------------------------------------------------------------------------
59// サンプルコードの実行: Dom\Notation インスタンスの取得と比較の実演
60// -----------------------------------------------------------------------------
61
62// DTD（Document Type Definition）で <!NOTATION> を定義したXML文字列
63$xmlString = <<<XML
64<?xml version="1.0"?>
65<!DOCTYPE example [
66  <!-- 'gif' という名前で、システム識別子 'image/gif' を持つ記法を定義 -->
67  <!NOTATION gif SYSTEM "image/gif">
68  <!ELEMENT root (#PCDATA|child)*>
69  <!ELEMENT child EMPTY>
70  <!ATTLIST root
71    imageType NOTATION (gif) #REQUIRED>
72]>
73<example imageType="gif">
74  <root>
75    <child/>
76    <child/>
77    DOM Content Example
78  </root>
79</example>
80XML;
81
82try {
83    $dom = new \Dom\Document();
84    // XMLをロードしてパースする
85    $dom->loadXML($xmlString);
86
87    $notationNode = null;
88
89    // DTDから Dom\Notation インスタンスを取得します。
90    // Dom\DocumentType::notations は Dom\NamedNodeMap を返します。
91    if ($dom->doctype && $dom->doctype->notations->length > 0) {
92        /** @var \Dom\Notation $notationNode */
93        $notationNode = $dom->doctype->notations->item(0); // 最初のNotationを取得
94        echo "成功: DTDからNotationノード '{$notationNode->nodeName}' (systemId: '{$notationNode->systemId}') を取得しました。" . PHP_EOL;
95    } else {
96        echo "エラー: XMLからNotationノードが見つかりませんでした。DTD定義を確認してください。" . PHP_EOL;
97        exit(1);
98    }
99
100    echo PHP_EOL;
101
102    // 1. 同じ Dom\Notation ノード同士の比較
103    // 結果: Same Node (0x20)
104    compareDomNodePositions($notationNode, $notationNode);
105
106    // 2. Dom\Notation ノードとドキュメントのルート要素 (<example>) との比較
107    // Dom\Notation は DTD の一部であり、DOMツリーの要素とは直接的な階層関係がないため、
108    // 通常は Disconnected (0x01) となります。
109    if ($dom->documentElement) {
110        compareDomNodePositions($notationNode, $dom->documentElement);
111    }
112
113    // 3. Dom\Notation ノードとドキュメント自体との比較
114    // Dom\Document も Dom\Node を実装していますが、Dom\Notation とは Disconnected となります。
115    compareDomNodePositions($notationNode, $dom);
116
117    // 4. Dom\Notation ノードとツリー内の別の要素 (<child>) との比較
118    $firstElement = $dom->getElementsByTagName('child')->item(0);
119    if ($firstElement) {
120        compareDomNodePositions($notationNode, $firstElement);
121    }
122
123} catch (\Dom\Exception $e) {
124    echo "DOM操作中にエラーが発生しました: " . $e->getMessage() . PHP_EOL;
125} catch (\Throwable $e) {
126    echo "予期せぬエラーが発生しました: " . $e->getMessage() . PHP_EOL;
127}

Dom\Notation::compareDocumentPositionメソッドは、現在のDom\Notationノードと、引数で指定された別のDom\Nodeノードの相対的な位置関係を比較するために使用されます。Dom\NotationはXMLのDTDで定義される特別なノードであり、通常のDOMツリーの要素などとは構造的に異なるため、多くの場合「Disconnected（切断された）」という関係になります。

引数$otherには比較対象となる任意のDom\Node型のノードを指定します。戻り値は整数値で、ノード間の複数の位置関係をビットマスクとして表現します。この値は、Dom\Nodeクラスの定数（例えばDOCUMENT_POSITION_DISCONNECTED、DOCUMENT_POSITION_PRECEDING、DOCUMENT_POSITION_FOLLOWINGなど）とビット論理積（&）を使って比較することで、具体的な関係を判別できます。

サンプルコードでは、DTDから取得したDom\Notationノードと、同じノード自身、XMLドキュメントのルート要素、ドキュメント自体、そしてツリー内の子要素を比較しています。これにより、ノードが同じである場合は「Same Node」、異なるツリー構造に属する場合は「Disconnected」といったように、それぞれの位置関係がどのようにビットマスクとして表現されるかを確認し、DOMノード間の複雑な関係性を理解するのに役立ちます。

Copy
1<?php
2
3/**
4 * このファイルは、PHPの Dom\Notation::compareDocumentPosition メソッドの使用例を示します。
5 * システムエンジニアを目指す初心者向けに、Dom\Notation の基本的な取得方法と、
6 * その他の DOM ノードとの位置関係を比較する方法を簡潔に示します。
7 *
8 * phpdocumentor などのドキュメント生成ツールが解析しやすいよう、PHPDoc コメントを適切に記述しています。
9 */
10
11/**
12 * 2つの DOM ノード間のドキュメント位置を比較し、結果を人間が読める形式で返します。
13 *
14 * `Dom\Notation` オブジェクトは DOM ツリーに直接接続されるノードではないため、
15 * 他のノードと比較した場合、通常は `DOM_DOCUMENT_POSITION_DISCONNECTED` が返されます。
16 * これは、`Dom\Notation` がツリー内で物理的な位置を持たないことに起因します。
17 *
18 * @param Dom\Node $node1 比較元のノード（Dom\Notation またはその他の Dom\Node）
19 * @param Dom\Node $node2 比較対象のノード（Dom\Node）
20 * @return string 比較結果を説明する文字列
21 */
22function compareAndDescribePosition(Dom\Node $node1, Dom\Node $node2): string
23{
24    // compareDocumentPosition メソッドは、2つのノード間の位置関係を示すビットフラグを返します。
25    $position = $node1->compareDocumentPosition($node2);
26    $description = [];
27
28    // 返されたビットフラグをAND演算子でチェックし、各定数の意味を解釈します。
29    if ($position & \DOM_DOCUMENT_POSITION_DISCONNECTED) {
30        $description[] = 'ノードは切断されています (異なるドキュメント、またはDOMツリーに接続されていない)';
31    }
32    if ($position & \DOM_DOCUMENT_POSITION_PRECEDING) {
33        $description[] = '比較元ノードが比較対象ノードの前にあります';
34    }
35    if ($position & \DOM_DOCUMENT_POSITION_FOLLOWING) {
36        $description[] = '比較元ノードが比較対象ノードの後にあります';
37    }
38    if ($position & \DOM_DOCUMENT_POSITION_CONTAINS) {
39        $description[] = '比較元ノードが比較対象ノードを含んでいます';
40    }
41    if ($position & \DOM_DOCUMENT_POSITION_CONTAINED_BY) {
42        $description[] = '比較元ノードが比較対象ノードに含まれています';
43    }
44    if ($position & \DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
45        $description[] = '実装固有の動作';
46    }
47
48    // position が 0 の場合（ノードが同じ、または位置関係が特定できない場合など）
49    if (empty($description)) {
50        return 'ノードは同じです (または位置関係が特定できません)';
51    }
52
53    return implode(', ', $description);
54}
55
56// DTD（Document Type Definition）で NOTATION が定義されたXML文字列を用意します。
57// Dom\Notation オブジェクトは、この NOTATION 宣言から取得されます。
58$xmlString = <<<XML
59<?xml version="1.0" encoding="UTF-8"?>
60<!DOCTYPE document [
61  <!NOTATION gif SYSTEM "image/gif">
62  <!NOTATION jpeg SYSTEM "image/jpeg">
63  <!ELEMENT document (item*)>
64  <!ELEMENT item (#PCDATA)>
65  <!ATTLIST item
66    id CDATA #REQUIRED
67    type NOTATION (gif | jpeg) #IMPLIED
68  >
69]>
70<document>
71  <item id="img1" type="gif">A GIF image reference.</item>
72  <item id="img2" type="jpeg">A JPEG image reference.</item>
73</document>
74XML;
75
76try {
77    // DOMDocument のインスタンスを作成し、XML を読み込みます。
78    $dom = new DOMDocument();
79    $dom->loadXML($xmlString);
80    // DTD の検証を有効にすることで、NOTATION の存在を明確にします。
81    $dom->validateOnParse = true;
82
83    echo "--- Dom\\Notation::compareDocumentPosition の使用例 ---\n\n";
84
85    /**
86     * DOMDocument::doctype プロパティから Dom\DocumentType オブジェクトを取得します。
87     * これには XML ドキュメントの DTD 情報が含まれます。
88     *
89     * @var Dom\DocumentType|null $doctype
90     */
91    $doctype = $dom->doctype;
92
93    if ($doctype === null) {
94        echo "エラー: ドキュメントに DTD が見つかりませんでした。Dom\\Notation は DTD 内に定義されます。\n";
95        exit(1);
96    }
97
98    /**
99     * Dom\DocumentType::notations プロパティから、全ての NOTATION を取得します。
100     * これは Dom\NamedNodeMap のインスタンスです。
101     *
102     * @var Dom\NamedNodeMap $notations
103     */
104    $notations = $doctype->notations;
105
106    if ($notations->length === 0) {
107        echo "エラー: DTD に NOTATION が定義されていませんでした。\n";
108        exit(1);
109    }
110
111    /**
112     * 'gif' という名前の NOTATION を取得します。
113     * これが Dom\Notation クラスのインスタンスです。
114     *
115     * @var Dom\Notation $gifNotation
116     */
117    $gifNotation = $notations->getNamedItem('gif');
118
119    if ($gifNotation === null) {
120        echo "エラー: 'gif' NOTATION が見つかりませんでした。\n";
121        exit(1);
122    }
123
124    // 比較対象となる DOM ツリー内の要素ノードを取得します。
125    /** @var DOMElement $firstItemElement 最初の <item> 要素ノード */
126    $firstItemElement = $dom->getElementsByTagName('item')->item(0);
127
128    /** @var DOMElement $secondItemElement 2番目の <item> 要素ノード */
129    $secondItemElement = $dom->getElementsByTagName('item')->item(1);
130
131    if ($firstItemElement === null || $secondItemElement === null) {
132        echo "エラー: 比較対象の要素ノードが見つかりませんでした。\n";
133        exit(1);
134    }
135
136    echo "比較元: 'gif' Notation (Dom\\Notation オブジェクト)\n";
137
138    // Dom\Notation と DOM ツリー内の要素ノードの比較
139    echo "  - 比較対象: 最初の <item> 要素\n";
140    echo "    結果: " . compareAndDescribePosition($gifNotation, $firstItemElement) . "\n\n";
141    // Dom\Notation は DOM ツリーに直接接続されないため、通常は "ノードは切断されています" となります。
142
143    // 異なる Dom\Notation オブジェクト間の比較
144    /** @var Dom\Notation $jpegNotation 'jpeg' という名前の NOTATION を取得 */
145    $jpegNotation = $notations->getNamedItem('jpeg');
146    if ($jpegNotation !== null) {
147        echo "  - 比較対象: 'jpeg' Notation (別の Dom\\Notation オブジェクト)\n";
148        echo "    結果: " . compareAndDescribePosition($gifNotation, $jpegNotation) . "\n\n";
149        // Dom\Notation 同士の比較も、DOMツリー内での物理的な位置関係ではないため、
150        // "ノードは切断されています" となる可能性が高いです。
151    } else {
152        echo "    エラー: 'jpeg' NOTATION が見つかりませんでした。\n\n";
153    }
154
155    // 補足: 通常の DOM ノード間の比較例 (Dom\Notation::compareDocumentPosition とは直接関係ありませんが、参考として)
156    echo "--- 参考: 通常の DOM ノード間の比較例 ---\n\n";
157    echo "比較元: 最初の <item> 要素\n";
158    echo "  - 比較対象: 2番目の <item> 要素\n";
159    echo "    結果: " . compareAndDescribePosition($firstItemElement, $secondItemElement) . "\n\n";
160    // 期待される結果: 最初の要素が2番目の要素の「前に」あるため、"比較元ノードが比較対象ノードの前にあります"
161
162    echo "  - 比較対象: 同じ <item> 要素自身\n";
163    echo "    結果: " . compareAndDescribePosition($firstItemElement, $firstItemElement) . "\n\n";
164    // 期待される結果: ノードが同じであるため、"ノードは同じです"
165
166} catch (Exception $e) {
167    echo "スクリプト実行中にエラーが発生しました: " . $e->getMessage() . "\n";
168}

PHP 8で提供される Dom\Notation::compareDocumentPosition メソッドは、XMLドキュメントのDTD（Document Type Definition）で定義される「記法」を表す Dom\Notation オブジェクトと、他のDOMノードとの位置関係を比較する際に使用されます。このメソッドは Dom\Node $other を引数に取り、比較対象のノードを指定します。戻り値は int 型のビットフラグで、DOM_DOCUMENT_POSITION_DISCONNECTED（切断されている）、DOM_DOCUMENT_POSITION_PRECEDING（前に位置する）などの複数の情報が組み合わされて返されます。

Dom\Notation オブジェクトは、XMLドキュメントの実際のツリー構造に直接接続されるノードではないため、ほとんどの場合、他のDOMツリー内のノードと比較すると「切断されている」（DOM_DOCUMENT_POSITION_DISCONNECTED）という結果が返されます。サンプルコードでは、まずXMLのDTD情報から Dom\Notation を取得し、その Dom\Notation とドキュメント内の要素ノードを比較しています。結果が「切断されています」となることが確認でき、これは Dom\Notation がツリー内で物理的な位置を持たないことによる挙動です。また、phpdocumentor などのツールがコードを解析しやすいよう、PHPDocコメントを記述する重要性も示しています。通常のDOMノード間の比較例も含まれており、メソッドの一般的な動作も理解しやすくなっています。