【PHP8.x】DOMEntityReference::contains()メソッドの使い方

Copy
1<?php
2
3/**
4 * 配列に指定した要素が含まれているかを確認します。
5 *
6 * PHPで配列に特定の要素が含まれているか（contains）を確認する最も一般的な方法は、
7 * in_array() 関数を使用することです。
8 *
9 * @param array<string> $haystack 検索対象の配列
10 * @param string $needle 検索する値
11 * @return void
12 */
13function checkValueInArray(array $haystack, string $needle): void
14{
15    // in_array() は、第1引数に指定した値が第2引数の配列内に存在するかを判定します。
16    // 存在すれば true を、しなければ false を返します。
17    // 第3引数に true を指定すると、型も厳密に比較します (例: 1 と "1" を区別する)。
18    if (in_array($needle, $haystack, true)) {
19        echo "配列に '{$needle}' は含まれています。\n";
20    } else {
21        echo "配列に '{$needle}' は含まれていません。\n";
22    }
23}
24
25// サンプルの配列
26$fruits = ['apple', 'banana', 'orange'];
27
28// 配列に含まれている値をチェックする例
29checkValueInArray($fruits, 'banana');
30
31// 配列に含まれていない値をチェックする例
32checkValueInArray($fruits, 'grape');
33
34?>

このPHPサンプルコードは、in_array() 関数を利用して、指定した配列内に特定の要素が含まれているかどうかを確認する基本的な方法を示しています。

コード内では checkValueInArray という独自の関数が定義されています。この関数は、第1引数 $haystack で検索対象となる配列を、第2引数 $needle で検索したい値を受け取ります。この関数の戻り値の型は void であり、これは関数が処理結果を返さず、判定結果のメッセージを echo を使って画面に直接出力することを意味します。

関数の中心的な処理は in_array() 関数によって行われます。これは、$haystack 配列内に $needle の値が存在すれば true を、存在しなければ false を返すPHPの組み込み関数です。サンプルコードのように第3引数に true を渡すと、値だけでなくデータ型も一致するかどうかを厳密に比較します。

実行部分では、$fruits 配列に対して、実際に含まれている 'banana' と含まれていない 'grape' をそれぞれ検索し、関数の動作を確認しています。

Copy
1<?php
2
3/**
4 * このクラスは、提供されたリファレンス情報に基づき、DOMEntityReferenceクラスの
5 * 存在しないcontains()メソッドの振る舞いを模倣するために作成されました。
6 *
7 * 注: PHPの標準DOM拡張には、DOMEntityReferenceクラスにcontains()メソッドは存在しません。
8 * また、DOMEntityReferenceクラスは通常、DOMDocument::loadXML()などによって
9 * 自動的に生成されるものであり、直接インスタンス化することは稀です。
10 */
11class MockDOMEntityReference
12{
13    /**
14     * 提供されたリファレンス情報に基づき、voidを返すcontainsメソッドを定義します。
15     * 通常、'contains'という名前のメソッドは真偽値を返しますが、
16     * リファレンスが「戻り値なし」と指定しているため、それに従います。
17     *
18     * @param ?DOMNode $other 比較対象のノード、または null。
19     */
20    public function contains(?DOMNode $other): void
21    {
22        // リファレンス情報が「戻り値なし」と指定しているため、ここでは具体的な
23        // 包含チェックロジックは実装せず、呼び出されたことを示すメッセージを出力します。
24        echo "MockDOMEntityReference::contains() が呼び出されました。\n";
25
26        if ($other === null) {
27            echo "  引数として null が渡されました。\n";
28        } elseif ($other instanceof DOMNode) {
29            echo "  引数として DOMNode (nodeName: " . $other->nodeName . ") が渡されました。\n";
30        } else {
31            echo "  引数として予期しない型が渡されました。\n"; // ?DOMNode なのでここは通常到達しない
32        }
33        echo "  (このメソッドは提供されたリファレンスに従い、何も値を返しません。)\n";
34    }
35}
36
37/**
38 * DOMEntityReference::contains() メソッドの呼び出し例を示します。
39 *
40 * この関数は、上記の MockDOMEntityReference クラスを使用しています。
41 */
42function demonstrateDomEntityReferenceContainsExample(): void
43{
44    // ダミーの DOMDocument を作成し、DOMNode を生成するために使用
45    $dom = new DOMDocument();
46    $dom->loadXML('<root><element id="e1"/></root>');
47
48    // MockDOMEntityReference のインスタンスを作成
49    $entityRef = new MockDOMEntityReference();
50
51    // 比較対象となるDOMノードをいくつか作成
52    $node1 = $dom->createElement('test_node_1');
53    $node2 = $dom->getElementById('e1'); // ドキュメント内の既存ノード
54
55    echo "--- DOMEntityReference::contains() メソッドのサンプルコード ---\n\n";
56
57    // 1. null を引数として渡す例
58    echo "ケース 1: null を引数として渡す\n";
59    $entityRef->contains(null);
60    echo "\n";
61
62    // 2. 存在するDOMノードを引数として渡す例
63    echo "ケース 2: DOMNode を引数として渡す (作成されたノード)\n";
64    $entityRef->contains($node1);
65    echo "\n";
66
67    // 3. ドキュメント内の既存のDOMノードを引数として渡す例
68    echo "ケース 3: DOMNode を引数として渡す (既存のドキュメントノード)\n";
69    $entityRef->contains($node2);
70    echo "\n";
71
72    echo "このサンプルは、リファレンス情報で指定されたメソッドシグネチャ (引数: ?DOMNode, 戻り値: void) に\n";
73    echo "従った動作を示しています。\n";
74}
75
76// サンプルコードを実行
77demonstrateDomEntityReferenceContainsExample();

PHP 8のDOM拡張機能には、XMLやHTMLのエンティティ参照を表すDOMEntityReferenceクラスがあります。このクラスに存在するcontainsメソッドは、特定のDOMNodeがエンティティ参照の範囲内に含まれているかを確認するためのものと想定されます。

containsメソッドは、引数として?DOMNode $otherを受け取ります。これは、比較対象となるDOMNodeオブジェクト、またはnullのいずれかを指定できることを意味します。メソッドが呼び出されると、このDOMEntityReferenceインスタンスが引数で指定されたotherノードを包含しているかを内部的に評価することが期待されます。

しかし、このメソッドの戻り値は「戻り値なし（void）」と定義されています。これは、メソッドが包含チェックの処理を実行するだけで、その結果（例えば、trueかfalseなどの真偽値）を呼び出し元に直接返さないことを意味します。一般的なcontainsメソッドは真偽値を返しますが、提供されたリファレンス情報に従うと、このメソッドは結果を返さずに処理を完了する設計であると考えられます。

サンプルコードは、標準のPHPにはこのcontainsメソッドが存在しないため、その動作を模倣したMockDOMEntityReferenceクラスを使用しています。このモッククラスのcontainsメソッドは、引数としてnullや異なるDOMNodeオブジェクトが渡された際に、渡された引数の種類を表示するだけで、実際の包含チェックは行いません。このサンプルは、?DOMNode型の引数を渡し、voidの戻り値を持つメソッドの呼び出し方と、その基本的な挙動を理解するためのものです。