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

Copy
1<?php
2
3/**
4 * Dom\Notation::isConnected プロパティの使用例を示します。
5 * このプロパティは、Dom\Notation ノードがDOMツリーに接続されているかを示します。
6 * Dom\Notation は、XMLドキュメントのDOCTYPE宣言内で定義されるNOTATION要素を表します。
7 *
8 * NOTATIONは、XMLドキュメント内で外部の非XMLデータ形式（例: 画像フォーマット）を参照するために使用されます。
9 * 例えば、画像ファイルが'gif'フォーマットであることをDTDで宣言する際に利用されます。
10 */
11function demonstrateDomNotationIsConnected(): void
12{
13    // DOMDocument オブジェクトを新規作成します。
14    $dom = new DOMDocument();
15    // 厳密なエラーチェックを有効にし、DTDのバリデーションエラーを警告として表示します。
16    $dom->validateOnParse = true;
17
18    // NOTATION定義を含むXML文字列を準備します。
19    // ここでは'gif'と'jpeg'という2つのNOTATIONを定義しています。
20    $xmlString = <<<XML
21<?xml version="1.0"?>
22<!DOCTYPE root [
23  <!-- 'gif' という名前のNOTATIONを定義。公開識別子のみを持つ外部リソース用 -->
24  <!NOTATION gif PUBLIC "-//W3C//DTD GIF//EN">
25  <!-- 'jpeg' という名前のNOTATIONを定義。システム識別子を持つ外部リソース用 -->
26  <!NOTATION jpeg SYSTEM "http://example.com/jpeg-handler">
27  <!-- このDTDは、外部システムIDを持つ特定の画像フォーマットを識別するために使われます。 -->
28  <!ENTITY myImage SYSTEM "image.gif" NDATA gif>
29]>
30<root>
31    <image src="logo.gif" type="gif"/>
32</root>
33XML;
34
35    // XML文字列をDOMドキュメントにロードします。
36    // エラーが発生した場合に備えてチェックを行います。
37    if (!$dom->loadXML($xmlString)) {
38        echo "エラー: XMLドキュメントのロードに失敗しました。" . PHP_EOL;
39        return;
40    }
41
42    // ドキュメントの DOCTYPE (Document Type Definition) オブジェクトを取得します。
43    // Dom\Notation オブジェクトは DOMDocumentType オブジェクトの notations プロパティからアクセスされます。
44    $doctype = $dom->doctype;
45
46    if ($doctype === null) {
47        echo "情報: ドキュメントにDOOCTYPEが見つかりませんでした。" . PHP_EOL;
48        return;
49    }
50
51    // DOCTYPEに定義されたすべてのNOTATIONノードのマップを取得します。
52    // notations プロパティは DOMNamedNodeMap を返します。
53    $notationMap = $doctype->notations;
54
55    echo "--- NOTATION 'gif' の状態確認 ---" . PHP_EOL;
56    // 'gif' という名前の Dom\Notation オブジェクトを取得します。
57    // getNamedItem() は指定された名前のノードを返します。
58    /** @var Dom\Notation|null $gifNotation */
59    $gifNotation = $notationMap->getNamedItem('gif');
60
61    if ($gifNotation instanceof Dom\Notation) {
62        // isConnected プロパティの値を出力します。
63        // ドキュメントにロードされたNOTATIONは、DOMツリーの一部として常に接続状態にあると見なされます。
64        echo "Notation 'gif' はDOMツリーに接続されています: "
65             . ($gifNotation->isConnected ? 'true' : 'false') . PHP_EOL;
66    } else {
67        echo "情報: NOTATION 'gif' はDOOCTYPE内で見つかりませんでした。" . PHP_EOL;
68    }
69
70    echo PHP_EOL;
71
72    echo "--- NOTATION 'jpeg' の状態確認 ---" . PHP_EOL;
73    /** @var Dom\Notation|null $jpegNotation */
74    $jpegNotation = $notationMap->getNamedItem('jpeg');
75
76    if ($jpegNotation instanceof Dom\Notation) {
77        echo "Notation 'jpeg' はDOMツリーに接続されています: "
78             . ($jpegNotation->isConnected ? 'true' : 'false') . PHP_EOL;
79    } else {
80        echo "情報: NOTATION 'jpeg' はDOOCTYPE内で見つかりませんでした。" . PHP_EOL;
81    }
82
83    echo PHP_EOL;
84
85    echo "--- 存在しないNOTATION ('bmp') の状態確認 ---" . PHP_EOL;
86    /** @var Dom\Notation|null $unknownNotation */
87    $unknownNotation = $notationMap->getNamedItem('bmp');
88    if ($unknownNotation instanceof Dom\Notation) {
89        echo "Notation 'bmp' はDOMツリーに接続されています: "
90             . ($unknownNotation->isConnected ? 'true' : 'false') . PHP_EOL;
91    } else {
92        // この場合はNOTATIONが見つからないため、nullが返されます。
93        echo "情報: NOTATION 'bmp' はDOOCTYPE内で見つかりませんでした。" . PHP_EOL;
94    }
95}
96
97// 関数を実行します。
98demonstrateDomNotationIsConnected();

PHP 8のDom\Notation::isConnectedプロパティは、XMLドキュメントのDTD（Document Type Definition）内で定義されるNOTATIONノードが、DOM（Document Object Model）ツリーに接続されているかどうかを示すブール値です。Dom\Notationは、XMLドキュメント内で画像などの外部の非XMLデータ形式を参照する際に利用されます。このプロパティは引数を取らず、ノードがDOMツリーの一部として存在していればtrueを、そうでなければfalseを返します。

サンプルコードでは、まずNOTATION定義を含むXMLドキュメントをDOMDocumentオブジェクトにロードしています。その後、ドキュメントのdoctypeプロパティからnotationsマップを取得し、そこから特定の名前（例として'gif'や'jpeg'）でDom\Notationオブジェクトを取得します。取得したDom\Notationオブジェクトに対してisConnectedプロパティにアクセスすることで、そのNOTATIONがDOMツリーに接続されているかを確認できます。通常、XMLドキュメントがロードされ、DOCTYPE内で定義されたNOTATIONはDOMツリーに接続されていると判断されるため、trueが返される挙動が確認できます。存在しないNOTATIONについては、オブジェクト自体が取得できないため、このプロパティにアクセスすることはできません。

Copy
1<?php
2
3/**
4 * Dom\Notation::isConnected プロパティの使用例を示します。
5 *
6 * このプロパティは、DOMノードがそのドキュメントツリーに接続されているかどうかを示します。
7 * アプリケーションにおいて、システムコンポーネント（例: データベース接続、外部サービス接続、Pahoクライアントなど）
8 * が意図した状態で「接続されている」ことを確認することは、システムの安定性を保つ上で不可欠です。
9 * ここでは、DOMツリーにおけるノードの接続状態を確認するパターンを紹介します。
10 */
11function checkDomNotationConnectionStatus(): void
12{
13    // DTD (Document Type Definition) を含むXML文字列を定義します。
14    // Dom\Notationは通常、DTD内で定義されます。
15    $xml = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<!DOCTYPE root [
18    <!NOTATION myimage PUBLIC "image/jpeg">
19    <!ELEMENT root ANY>
20]>
21<root/>
22XML;
23
24    // DOMDocumentオブジェクトを作成し、XMLをロードします。
25    $dom = new DOMDocument();
26    $dom->loadXML($xml);
27
28    // XMLのDocument Type (DOCTYPE) を取得します。
29    $documentType = $dom->doctype;
30    $notation = null;
31
32    // DTDが定義されており、notationが存在する場合、最初のnotationを取得します。
33    // Dom\NotationはDom\Nodeを継承しており、isConnectedプロパティを持ちます。
34    if ($documentType instanceof DOMDocumentType && $documentType->notations->length > 0) {
35        /** @var \Dom\Notation $notation */
36        $notation = $documentType->notations->item(0);
37    }
38
39    // Dom\Notationインスタンスが取得できた場合、そのisConnectedプロパティを確認します。
40    // DTD内のnotationは、ドキュメントがロードされた時点でツリーに接続されているため、
41    // 通常この値は true になります。
42    if ($notation instanceof Dom\Notation) {
43        echo "Dom\\Notation '{$notation->nodeName}' (Public ID: {$notation->publicId}) はドキュメントに接続されていますか？: "
44            . ($notation->isConnected ? 'はい' : 'いいえ') . "\n";
45    } else {
46        echo "Dom\\Notation インスタンスが見つかりませんでした。\n";
47    }
48
49    // (参考) 一般的なDom\NodeにおけるisConnectedプロパティの振る舞い
50    // Dom\Notationは通常ドキュメントの一部として常に接続されていますが、
51    // 一般的なノードでは、接続状態が変化する様子を確認できます。
52    $temporaryNode = $dom->createElement('temporaryElement');
53    echo "\n新しく作成されたノード '{$temporaryNode->nodeName}' はドキュメントに接続されていますか？: "
54        . ($temporaryNode->isConnected ? 'はい' : 'いいえ') . "\n"; // 結果: いいえ (まだツリーに追加されていない)
55
56    // ノードをドキュメントツリーに追加します。
57    $dom->documentElement->appendChild($temporaryNode);
58    echo "ドキュメントに追加されたノード '{$temporaryNode->nodeName}' は接続されていますか？: "
59        . ($temporaryNode->isConnected ? 'はい' : 'いいえ') . "\n"; // 結果: はい (ツリーに接続された)
60}
61
62// 関数を実行します。
63checkDomNotationConnectionStatus();
64

Dom\Notation::isConnectedプロパティは、PHPのDOM拡張機能において、XMLの文書型定義（DTD）内で定義されるNOTATIONノードが、現在そのDOMドキュメントツリーに接続されているかどうかを示す真偽値（ブール値）を返します。このプロパティは引数を取りません。戻り値は、該当するノードがドキュメントツリーの一部である場合にtrueを、そうでなければfalseを返します。

サンプルコードでは、DTDを含むXMLをロードし、その中からNOTATIONノードを取得しています。Dom\Notationは通常DTD内で定義されるため、ドキュメントがロードされた時点でほとんどの場合、既にドキュメントツリーに接続されており、isConnectedプロパティはtrueを返します。コードでは、この接続状態を確認し、結果を出力しています。

また、参考として一般的なDOMノードの挙動も示しています。新しく作成されたノードはドキュメントツリーにまだ追加されていないためisConnectedはfalseとなり、その後ドキュメントツリーに追加されるとtrueに変化する様子が確認できます。このようにノードがドキュメントツリーに属しているかを確認することは、DOM操作における整合性の確保に役立ちます。

この「接続されているか」という状態確認の概念は、DOMノードだけでなく、データベース接続や外部サービス、例えばPahoクライアントのようなメッセージブローカーへの接続が意図した状態であるかを確認するなど、システム全体の安定性を保つ上で広く重要な考え方となります。