【PHP8.x】Dom\EntityReference::isConnectedプロパティの使い方

Copy
1<?php
2
3/**
4 * Dom\EntityReference::isConnected プロパティの使用例を示します。
5 *
6 * この関数は、XML/HTML ドキュメントのDOM (Document Object Model) 操作に関連する
7 * Dom\EntityReference オブジェクトの isConnected プロパティの動作を実演します。
8 *
9 * isConnected プロパティは、Dom\Node (Dom\EntityReference もこれを継承) が
10 * Dom\Document の子孫として実際にドキュメントツリーに接続されているかどうかを示します。
11 *
12 * なお、「isConnected」という用語は、ネットワーク接続（例：Paho MQTTクライアントがブローカーに接続されているか）
13 * など、他のプログラミングコンテキストでも広く使用される一般的な概念です。
14 */
15function demonstrateDomEntityReferenceIsConnected(): void
16{
17    // 新しい Dom\Document オブジェクトを作成します。
18    // Dom\EntityReference のインスタンスを作成するには、Dom\Document が必要です。
19    $dom = new Dom\Document('1.0', 'UTF-8');
20
21    // 'nbsp' (改行なしスペース) という名前のエンティティ参照を作成します。
22    // 注意: Dom\EntityReference は、通常の要素やテキストノードとは異なり、
23    // DOM ツリーに直接追加されることを意図していません。
24    // また、この例では DTD (Document Type Definition) を定義していないため、
25    // 'nbsp' エンティティが見つからないという警告が発生する可能性がありますが、
26    // ノード自体は作成されます。
27    $entityRef = $dom->createEntityReference('nbsp');
28
29    // 作成直後の Dom\EntityReference オブジェクトの isConnected プロパティの状態を表示します。
30    // Dom\EntityReference は DOM ツリーの直接の子孫としては扱われないため、
31    // このプロパティは通常 'false' を返します。
32    echo "Dom\\EntityReference の isConnected: " . ($entityRef->isConnected ? 'true' : 'false') . "\n";
33
34    // 補足: Dom\EntityReference オブジェクトを通常の Dom\Node のように
35    // Dom\Document に追加しようとすると、エラーが発生します。
36    // 例: $dom->appendChild($entityRef); // これはエラーになります。
37    // このため、Dom\EntityReference が isConnected で 'true' を返すシナリオは非常に限定的か、
38    // 通常は自動的にパースされる内部的な挙動に依存します。
39}
40
41// 関数を実行して、Dom\EntityReference::isConnected の動作を確認します。
42demonstrateDomEntityReferenceIsConnected();

PHP 8のDom\EntityReference::isConnectedプロパティは、XMLやHTMLドキュメントのDOM (Document Object Model) において、Dom\EntityReferenceオブジェクトがドキュメントツリーに実際に接続されているかどうかを示す真偽値を取得します。このプロパティは引数を取らず、戻り値としてbool型（真偽値）を返します。接続されていればtrue、そうでなければfalseです。

サンプルコードでは、Dom\Documentオブジェクトを作成し、そこからnbspという名前のエンティティ参照（Dom\EntityReference）を生成しています。生成直後のentityRef->isConnectedプロパティの値を確認するとfalseが表示されます。これは、Dom\EntityReferenceが通常の要素ノードとは異なり、DOMツリーに直接追加されることを意図していないためです。通常、エンティティ参照はパーサーによって自動的に処理される内部的なノードとして扱われます。

「isConnected」という用語は、Paho MQTTクライアントがブローカーに接続されているかのように、ネットワーク接続の文脈でも使われる一般的な概念です。しかし、このPHPのDom\EntityReferenceプロパティにおいては、あくまでDOMツリーへの接続状況を意味する点に注意が必要です。

Copy
1<?php
2
3/**
4 * Dom\EntityReference::isConnected プロパティの使用例を示します。
5 *
6 * このプロパティは、DOMツリー内のエンティティ参照ノードが、
7 * 現在ドキュメントに接続されている（つまり、ドキュメントの一部である）かを
8 * 確認するために使用されます。
9 *
10 * `isConnected` は、DOMノードのツリー内での状態を示すものであり、
11 * 「paho connection lost」のようなネットワーク接続の状態とは異なる概念です。
12 * しかし、何らかの要素が「接続されているか」という状態を判断する際に利用できます。
13 */
14function checkDomEntityReferenceConnectionStatus(): void
15{
16    echo "--- DOM EntityReference::isConnected の動作確認 ---\n\n";
17
18    // 1. 新しいDOMDocumentインスタンスを作成します。
19    $dom = new DOMDocument('1.0', 'UTF-8');
20    // 可読性を高めるために空白を保持せず、整形して出力します。
21    $dom->preserveWhiteSpace = false;
22    $dom->formatOutput = true;
23
24    // 2. エンティティ参照ノードを作成します。（例: &amp;）
25    // この時点では、まだDOMツリーには追加されていません。
26    $entityRef = $dom->createEntityReference('amp');
27
28    echo "エンティティ参照 '&amp;' を作成しました。\n";
29    // isConnected プロパティは、ノードがドキュメントに接続されているかを示す真偽値を返します。
30    echo "  接続されていますか？: " . ($entityRef->isConnected ? "はい" : "いいえ") . "\n\n";
31
32    // 3. ルート要素を作成し、ドキュメントに追加します。
33    $root = $dom->createElement('root');
34    $dom->appendChild($root);
35
36    // 4. 作成したエンティティ参照ノードをルート要素の子として追加します。
37    // これにより、エンティティ参照ノードはDOMツリーに接続されます。
38    $root->appendChild($entityRef);
39
40    echo "エンティティ参照をルート要素に追加しました。\n";
41    echo "  接続されていますか？: " . ($entityRef->isConnected ? "はい" : "いいえ") . "\n\n";
42
43    // 5. DOMツリーからエンティティ参照ノードを削除します。
44    // これにより、エンティティ参照ノードはDOMツリーから切断されます。
45    $root->removeChild($entityRef);
46
47    echo "エンティティ参照をルート要素から削除しました。\n";
48    echo "  接続されていますか？: " . ($entityRef->isConnected ? "はい" : "いいえ") . "\n\n";
49
50    echo "--- 確認終了 ---\n";
51}
52
53// 関数を実行して、Dom\EntityReference::isConnected の動作を確認します。
54checkDomEntityReferenceConnectionStatus();

Dom\EntityReference::isConnectedプロパティは、PHPのDOM操作において、エンティティ参照ノードが現在DOMツリー、つまりドキュメントに接続されているかどうかを真偽値で判定します。このプロパティは引数を必要とせず、接続されていればtrue、接続されていなければfalseを返します。

サンプルコードでは、まずエンティティ参照ノード（例えば&）を作成します。この時点ではノードはまだDOMツリーに追加されていないため、isConnectedはfalseを示します。次に、作成したエンティティ参照ノードをDOMドキュメント内のルート要素の子として追加します。ノードがドキュメントに接続されると、isConnectedはtrueに変わります。その後、ノードをDOMツリーから削除すると、再びisConnectedはfalseとなり、ノードがドキュメントから切り離された状態を示します。

このisConnectedは、DOMツリー内でのノードの所属状態を判断するものであり、「paho connection lost」のようなネットワーク接続の有無とは根本的に異なる概念です。要素がドキュメントの一部として有効であるかをプログラムで確認する際に利用できます。