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

Copy
1<?php
2
3// PHP 8 の新しい DOM 拡張のクラス名をインポート
4use Dom\Document;
5use Dom\DocumentType;
6use Dom\Entity;
7use Dom\NamedNodeMap;
8
9/**
10 * Dom\Entity の ownerDocument プロパティと saveHTML() メソッドの使用例。
11 *
12 * この例では、DTD (Document Type Definition) で定義されたエンティティを含むXMLドキュメントを作成し、
13 * そのエンティティを表す Dom\Entity オブジェクトから ownerDocument を取得し、
14 * 最後にドキュメント全体のHTML表現を saveHTML() を使って出力します。
15 *
16 * Dom\Entity は通常、HTMLドキュメントではほとんど使用されません。
17 * これはXMLのDTDにおけるエンティティ宣言を表すため、XMLの例で示します。
18 */
19function demonstrateDomEntityOwnerDocumentAndSaveHtml(): void
20{
21    // DTDで「example」という名前のエンティティを定義したXML文字列
22    $xmlString = <<<XML
23<!DOCTYPE root [
24  <!ENTITY example "This is an example entity content.">
25]>
26<root>
27  <text>&example;</text>
28</root>
29XML;
30
31    // Dom\Document オブジェクトを新規作成
32    $document = new Document();
33
34    // XMLをロード。LIBXML_DTDLOAD を指定してDTDをパースさせ、エンティティ定義にアクセスできるようにします。
35    $document->loadXML($xmlString, LIBXML_DTDLOAD);
36
37    // Dom\DocumentType オブジェクトを取得
38    $documentType = $document->doctype;
39
40    /** @var Entity|null $foundEntity DTDから見つかった Dom\Entity オブジェクトを格納する変数 */
41    $foundEntity = null;
42
43    // ドキュメントタイプが存在し、かつエンティティのマップが存在する場合に処理
44    if ($documentType instanceof DocumentType && $documentType->entities instanceof NamedNodeMap) {
45        // DTDで定義されたエンティティのコレクションを検索
46        // ここでコレクションに含まれる各要素は Dom\Entity オブジェクトです。
47        foreach ($documentType->entities as $entityName => $entityNode) {
48            // "example" という名前の Dom\Entity オブジェクトを探す
49            if ($entityNode instanceof Entity && $entityName === 'example') {
50                $foundEntity = $entityNode;
51                break;
52            }
53        }
54    }
55
56    if ($foundEntity) {
57        echo "Dom\\Entity '" . $foundEntity->nodeName . "' がDTDから見つかりました。\n\n";
58
59        // Dom\Entity::ownerDocument プロパティにアクセス
60        // ownerDocument は、そのノードが属する Dom\Document オブジェクトを返します。
61        // すべての Dom\Node オブジェクト（Dom\Entity も含む）はこのプロパティを持ちます。
62        $ownerDocument = $foundEntity->ownerDocument;
63
64        if ($ownerDocument instanceof Document) {
65            echo "見つかった Dom\\Entity の ownerDocument を取得しました。\n\n";
66            echo "ドキュメント全体のHTML表現 (saveHTML):\n";
67
68            // 取得した ownerDocument に対して saveHTML() を呼び出し、HTML文字列として出力します。
69            // 注意: このドキュメントはXMLとしてロードされていますが、
70            //       キーワードに 'savehtml' が指定されているため saveHTML() を使用します。
71            //       通常、XMLドキュメントの出力には saveXML() を使用するべきです。
72            //       saveHTML() は、XMLをHTMLとして整形しようとするため、DTD情報が失われたり、
73            //       HTMLタグが付加されたりする場合があります。
74            echo $ownerDocument->saveHTML();
75        } else {
76            echo "エラー: ownerDocument が Dom\\Document オブジェクトではありませんでした。\n";
77        }
78    } else {
79        echo "エラー: 'example' という名前の Dom\\Entity が見つかりませんでした。\n";
80    }
81}
82
83// 関数を実行
84demonstrateDomEntityOwnerDocumentAndSaveHtml();

このPHPサンプルコードは、PHP 8の新しいDOM拡張機能を用いて、XMLドキュメント内のエンティティとドキュメント操作を示しています。

まず、DTD（Document Type Definition）で「example」という名前のエンティティを定義したXML文字列を作成します。このXMLをDom\DocumentオブジェクトにLIBXML_DTDLOADオプション付きで読み込むことで、DTDのエンティティ定義がパースされ、アクセス可能になります。

コードは、読み込んだドキュメントから「example」エンティティを表すDom\Entityオブジェクトを検索して取得します。Dom\Entity::ownerDocumentプロパティは、そのDom\Entityを含むすべてのDOMノードが持つプロパティです。このプロパティは引数を取らず、そのノードが属するDom\Documentオブジェクトを返します。ノードがまだドキュメントに属していない場合はnullを返しますが、この例では既にドキュメントにロードされているためDom\Documentオブジェクトが返されます。

最後に、取得したDom\Documentオブジェクトに対してsaveHTML()メソッドを呼び出しています。saveHTML()は、ドキュメント全体の構造をHTML形式の文字列として出力するメソッドです。このメソッドは、ドキュメントの内容をブラウザで表示されるようなHTMLとして整形して返します。ただし、このサンプルはXMLドキュメントを扱っているため、XMLの出力には通常saveXML()を使用する方が適切である点に注意が必要です。

Copy
1<?php
2
3/**
4 * Dom\Entity の ownerDocument プロパティの使用例。
5 * このプロパティは、XMLのDTDで定義される Dom\Entity が属する
6 * Dom\Document オブジェクトを返します。
7 */
8function demonstrateDomEntityOwnerDocument(): void
9{
10    // DTD で 'myentity' というエンティティを定義し、それを含む XML ドキュメントをロードします。
11    $xmlString = '<!DOCTYPE root [<!ENTITY myentity "My Entity Content">]><root>&myentity;</root>';
12    $dom = new DOMDocument();
13    $dom->loadXML($xmlString);
14
15    // ドキュメントの DTD からエンティティのコレクションを取得します。
16    // Dom\DocumentType::entities は Dom\NamedNodeMap|null を返します。
17    $entities = $dom->doctype?->entities;
18
19    if ($entities === null) {
20        echo "エラー: ドキュメントに DTD エンティティが見つかりませんでした。\n";
21        return;
22    }
23
24    // コレクションから 'myentity' という名前のエンティティを取得します。
25    // getNamedItem は Dom\Node|null を返しますが、ここでは Dom\Entity を期待します。
26    $entity = $entities->getNamedItem('myentity');
27
28    // 取得したノードが Dom\Entity のインスタンスであることを確認します。
29    if (!$entity instanceof Dom\Entity) {
30        echo "エラー: 'myentity' エンティティが見つからないか、Dom\\Entity 型ではありません。\n";
31        return;
32    }
33
34    // Dom\Entity::ownerDocument プロパティにアクセスし、所属ドキュメントを取得します。
35    // このプロパティの戻り値は ?Dom\Document (Dom\Document または null) です。
36    $ownerDocument = $entity->ownerDocument;
37
38    // ownerDocument が Dom\Document のインスタンスであることを確認します。
39    if ($ownerDocument instanceof DOMDocument) {
40        echo "Dom\\Entity の ownerDocument が正常に取得されました。\n";
41        echo "所属ドキュメントのクラス: " . get_class($ownerDocument) . "\n";
42
43        // 取得した ownerDocument が元の DOMDocument オブジェクトと同一であることを確認します。
44        if ($ownerDocument === $dom) {
45            echo "ownerDocument は、エンティティを作成した元の DOMDocument オブジェクトと同一です。\n";
46        }
47    } else {
48        // ownerDocument が取得できなかった、または null だった場合の処理です。
49        echo "Dom\\Entity の ownerDocument は取得できませんでした。\n";
50        if ($ownerDocument === null) {
51            echo "理由: ownerDocument は NULL でした。\n";
52        }
53    }
54}
55
56// 関数を実行してサンプルコードの動作を確認します。
57demonstrateDomEntityOwnerDocument();
58

PHPのDom\Entity::ownerDocumentプロパティは、XMLのDTD（文書型定義）で定義されたエンティティが「どのXMLドキュメントに属しているか」を調べる際に使用されます。このプロパティは引数を取らず、エンティティを作成・保持しているDom\Documentオブジェクトを戻り値として返します。戻り値の型は?Dom\Documentであり、通常はDom\Documentオブジェクトが返されますが、ごくまれにnullが返される可能性もあります。

サンプルコードでは、まずDTD内で「myentity」と定義されたエンティティを含むXMLドキュメントを読み込みます。次に、そのドキュメントから「myentity」に対応するDom\Entityオブジェクトを取得し、ownerDocumentプロパティにアクセスしています。これにより、エンティティが属するDom\Documentオブジェクトを取得できることを示しています。取得されたownerDocumentが、エンティティをロードした元のDOMDocumentオブジェクト（Dom\Documentのエイリアス）と同一であることを確認することで、このプロパティの挙動を明確に理解できます。このプロパティは、XML構造内で特定のエンティティがどのドキュメントに紐づいているかを特定する際に役立ちます。