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

Copy
1<?php
2
3// PHP 8.3 以降で利用可能な Dom\Attr::contains メソッドのサンプルコードです。
4// このメソッドは、ある Dom\Attr オブジェクトが別の Dom\Node または Dom\Attr オブジェクトを
5// 自身の子孫ノードとして含んでいるかを判定します。
6//
7// （注1: 提示されたリファレンス情報では「戻り値なし」と記載されていますが、
8// 実際のPHPの動作 (PHP 8.3以降) では bool 型の戻り値を返します。このサンプルコードは実際の動作に基づいています。）
9// （注2: Dom\Attr は通常、子ノードを持たないため、自身との比較以外ではほとんどの場合 false を返します。）
10//
11// キーワードに「array」が含まれていますが、Dom\Attr::contains メソッドはDOMノードの包含関係を扱うため、
12// PHPの配列操作とは直接関連しません。ここでは「contains」という概念をDOMの文脈で示します。
13
14function demonstrateAttrContains(): void
15{
16    echo "Dom\\Attr::contains メソッドのデモンストレーション\n";
17    echo "--------------------------------------------------\n\n";
18
19    // 1. DOMDocument オブジェクトを作成し、XML文字列を読み込みます。
20    //    これはテスト用のDOMツリーを構築する一般的な方法です。
21    $dom = new DOMDocument();
22    $dom->loadXML('<root><element id="my-id" data-value="test"><child-element/></element></root>');
23
24    // 2. 属性ノード (Dom\Attr) を取得します。
25    //    <element id="my-id" ...> の 'id' 属性ノードを取得します。
26    $element = $dom->getElementsByTagName('element')->item(0);
27    if (!$element) {
28        echo "要素が見つかりませんでした。\n";
29        return;
30    }
31    $attrId = $element->getAttributeNode('id'); // Dom\Attr オブジェクト 'id="my-id"'
32    if (!$attrId) {
33        echo "'id' 属性が見つかりませんでした。\n";
34        return;
35    }
36
37    // 3. 別の Dom\Node オブジェクトや Dom\Attr オブジェクトを準備します。
38    //    'data-value' 属性ノードを取得します。
39    $attrDataValue = $element->getAttributeNode('data-value'); // Dom\Attr オブジェクト 'data-value="test"'
40
41    //    子要素ノードを取得します。
42    $childElement = $dom->getElementsByTagName('child-element')->item(0); // <child-element/>
43
44    //    属性値のテキストノードを作成します。（これはDOMツリーに追加されていません）
45    //    多くのDOM実装では、属性値は属性ノードの子として扱われないため、contains は false になる傾向があります。
46    $textNodeForAttrValue = $dom->createTextNode('my-id');
47
48    // 4. Dom\Attr::contains() の使用例と結果
49
50    echo "対象属性: " . $attrId->nodeName . '="' . $attrId->nodeValue . '"' . "\n\n";
51
52    // 例1: 属性ノード自身との比較
53    // Dom\Attr::contains は、比較対象が自身である場合に true を返します。
54    $isContainingSelf = $attrId->contains($attrId);
55    echo "  attrId.contains(attrId): " . ($isContainingSelf ? 'true' : 'false') . "\n"; // 期待値: true
56
57    // 例2: 別の属性ノードとの比較
58    // 'id' 属性ノードが 'data-value' 属性ノードを子孫として含むことはありません。
59    $isContainingOtherAttr = $attrId->contains($attrDataValue);
60    echo "  attrId.contains(attrDataValue): " . ($isContainingOtherAttr ? 'true' : 'false') . "\n"; // 期待値: false
61
62    // 例3: 属性ノードの親要素との比較
63    // 属性ノードは要素の子ですが、要素が属性ノードの子孫になることはありません。
64    $isContainingParentElement = $attrId->contains($element);
65    echo "  attrId.contains(element): " . ($isContainingParentElement ? 'true' : 'false') . "\n"; // 期待値: false
66
67    // 例4: 属性ノードの子要素との比較
68    // 属性ノードが他の要素ノードを子孫として含むことはありません。
69    $isContainingChildElement = $attrId->contains($childElement);
70    echo "  attrId.contains(childElement): " . ($isContainingChildElement ? 'true' : 'false') . "\n"; // 期待値: false
71
72    // 例5: 属性値のテキストノードとの比較
73    // 属性ノードは、その値のテキストノードを子ノードとして持つかについてはDOM実装によって解釈が分かれることがあります。
74    // 一般的なDOMの Node.contains() の定義では、属性ノードは値のテキストノードを子として含まないことが多いです。
75    $isContainingTextNode = $attrId->contains($textNodeForAttrValue);
76    echo "  attrId.contains(textNodeForAttrValue): " . ($isContainingTextNode ? 'true' : 'false') . "\n"; // 期待値: false (ほとんどの場合)
77
78    echo "\n--------------------------------------------------\n";
79    echo "Dom\\Attr::contains メソッドは、自身のノードとの比較以外で true を返すことは稀です。\n";
80    echo "これは、属性ノードが通常子ノードを持たないためです。\n";
81}
82
83// 関数を実行してデモンストレーションを開始します。
84demonstrateAttrContains();

Dom\Attr::containsメソッドは、XMLやHTMLのDOM（Document Object Model）を操作する際に使用されるPHPの機能です。このメソッドは、特定のDom\Attrオブジェクト（属性ノード）が、引数で渡された別のDom\NodeまたはDom\Attrオブジェクトを自身の子孫ノードとして含んでいるかどうかを判定します。

引数$otherには、比較対象となるDom\NodeまたはDom\Attrオブジェクトを指定します。このメソッドは、PHP 8.3以降で利用可能であり、判定結果としてtrueまたはfalseのブール値を返します。trueは含まれていることを、falseは含まれていないことを示します。

しかし、属性ノードは通常、テキストノードをその値として持ちますが、DOMの標準的な解釈では子ノードを持つことはありません。そのため、このcontainsメソッドは、比較対象が属性ノード自身である場合を除き、ほとんどの場合falseを返します。例えば、ある属性ノードが、その属性が所属する要素や、その要素の子ノードを含むことはありません。このメソッドの挙動を理解する上で、この特性が非常に重要です。

提示されたキーワードに「array」がありますが、Dom\Attr::containsはDOMノードの階層関係を扱うものであり、PHPの配列操作とは直接的な関連はありません。このメソッドは、DOMツリー内でのノードの包含関係を確認する際に利用されます。

Copy
1<?php
2
3// Dom\Attr クラスの contains メソッドのサンプルコードです。
4// PHP 8 の DOM 拡張機能を使用します。
5
6// 1. DOMDocument オブジェクトを作成します。
7//    これはXML/HTMLドキュメントの全体を表します。
8$dom = new Dom\Document('1.0', 'UTF-8');
9
10// 2. ドキュメントのルート要素を作成し、ドキュメントに追加します。
11$rootElement = $dom->createElement('example');
12$dom->appendChild($rootElement);
13
14// 3. Dom\Attr オブジェクトを作成します。
15//    この属性は 'id' という名前を持ち、値を 'main-element' とします。
16$targetAttr = $dom->createAttribute('id');
17$targetAttr->value = 'main-element';
18
19// 4. 作成した属性をルート要素に設定します。
20//    これにより、<example id="main-element"></example> のようになります。
21$rootElement->setAttributeNode($targetAttr);
22
23// 5. contains メソッドの引数として使用する別の Dom\Attr オブジェクトを準備します。
24//    この属性は 'class' という名前を持ちます。
25$otherAttr = $dom->createAttribute('class');
26$otherAttr->value = 'highlight';
27
28// 6. Dom\Attr::contains() メソッドを呼び出します。
29//    引数として Dom\Attr オブジェクトを渡します。
30//    リファレンス情報によると、このメソッドには戻り値がありません。
31echo "Dom\\Attr::contains(\$otherAttr) を呼び出します。\n";
32$targetAttr->contains($otherAttr);
33echo "呼び出しが完了しました。\n"; // 戻り値がないため、呼び出し後の結果を評価する処理は行いません。
34
35echo "\n"; // 出力を見やすくするための改行
36
37// 7. contains メソッドの引数として使用する Dom\Node オブジェクトを準備します。
38//    ここでは、新しい要素ノードを作成します。
39$otherNode = $dom->createElement('child-node');
40// このノードは現在、ドキュメントツリーには追加されていません。
41
42// 8. Dom\Attr::contains() メソッドを再度呼び出します。
43//    引数として Dom\Node オブジェクトを渡します。
44echo "Dom\\Attr::contains(\$otherNode) を呼び出します。\n";
45$targetAttr->contains($otherNode);
46echo "呼び出しが完了しました。\n"; // 同様に、戻り値がないため結果の評価は行いません。

PHP 8のDOM拡張機能におけるDom\Attrクラスのcontainsメソッドは、DOMツリー内の属性を操作する際に利用されます。このメソッドは、呼び出し元のDom\Attrオブジェクト（HTMLのidやclassなどの属性を表すオブジェクト）に対して、引数として指定された別のDom\Nodeオブジェクト、またはDom\Attrオブジェクトが何らかの処理の対象となる場合に使用されます。

引数$otherには、DOMノードの基本となるDom\Nodeオブジェクトか、あるいは別のDom\Attrオブジェクトを指定します。例えば、HTML要素のid属性を表すDom\Attrオブジェクトに対して、他のclass属性（Dom\Attr）や、別の要素ノード（Dom\Node）を渡すことができます。

このメソッドの最も重要な特徴は、戻り値がないことです。一般的に、「含むかどうか」を判定するcontainsという名前のメソッドは、真偽値（trueまたはfalse）を返しますが、Dom\Attr::contains()メソッドは何も値を返しません。そのため、このメソッドを呼び出しても、直接的に何らかの判定結果や状態を示す値を得ることはできません。サンプルコードでも、メソッドの呼び出し後には特別な結果の評価が行われていないのは、この戻り値がないという挙動に基づいています。これは、メソッドが何らかの内部的な処理を実行する目的で設計されていることを示唆しています。