【PHP8.x】compareDocumentPositionメソッドの使い方

compareDocumentPositionメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年11月25日

基本的な使い方

compareDocumentPositionメソッドは、DOMTextノードと他のノードの相対的な位置関係を比較するメソッドです。

PHP 8のDOM拡張機能の一部であるDOMTextクラスに属しており、ドキュメントオブジェクトモデル（DOM）ツリー内でのノードの順序や包含関係を判別する際に利用されます。このメソッドは、引数として比較対象となるDOMNodeオブジェクトを一つ受け取ります。

戻り値は整数値で、これはDOMDocumentPosition定数で定義されたビットフラグの組み合わせとして、両ノード間の複数の位置関係を示します。具体的には、DOM_DOCUMENT_POSITION_DISCONNECTED (0x01) は二つのノードが異なるドキュメントに属しているか、あるいは比較できない位置にあることを示します。DOM_DOCUMENT_POSITION_PRECEDING (0x02) は引数のノードが呼び出し元のノードよりもドキュメント内で前に位置することを示し、DOM_DOCUMENT_POSITION_FOLLOWING (0x04) は引数のノードが呼び出し元のノードよりも後に位置することを示します。DOM_DOCUMENT_POSITION_CONTAINS (0x08) は呼び出し元のノードが引数のノードを内包していることを示し、DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10) は呼び出し元のノードが引数のノードに内包されていることを示します。また、DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20) は実装に依存する特定の状況下で比較ができないことを示します。

これらのフラグは排他的ではなく、同時に複数の関係性を示すためにビット論理演算子と組み合わせて使用することが可能です。このメソッドは、XMLやHTMLドキュメントの構造解析、ノードの順序検証、またはDOM操作における複雑な位置関係の判定など、多様な場面で役立ちます。

構文(syntax)


1<?php
2
3$textNode = new DOMText('Example Text');
4$otherNode = new DOMElement('div'); // 比較対象となる任意のDOMNodeオブジェクト
5
6$comparisonResult = $textNode->compareDocumentPosition($otherNode);

引数(parameters)

DOMNode $other

DOMNode $other: 比較対象となる DOMNode オブジェクト

戻り値(return)

int

このメソッドは、DOMTextノードと別のノードとの文書内での位置関係を示す整数値を返します。返される値はビットフラグの組み合わせであり、ノードが同じか、前にあるか、後ろにあるか、あるいは別の文書にあるかなどの情報を示します。