【PHP8.x】DOMEntity::actualEncodingプロパティの使い方

Copy
1<?php
2
3/**
4 * DOMEntity::actualEncoding プロパティの使用例を示します。
5 *
6 * この関数は、XMLドキュメント内のエンティティの実際のエンコーディングを取得し、表示します。
7 * システムエンジニアを目指す初心者向けに、DOMツリーの基本的な扱いやエンティティへのアクセス方法、
8 * そして特定のエンティティがどのようなエンコーディング情報を持っているかを理解してもらうことを目的としています。
9 */
10function demonstrateDomEntityActualEncoding(): void
11{
12    // DOMDocument オブジェクトを作成します。
13    // XML構造を解析し、DOMツリーを構築するために使用します。
14    $dom = new DOMDocument();
15
16    // XMLを読み込む際に空白ノードを無視する設定
17    // これにより、DOMツリーがより簡潔になります。
18    $dom->preserveWhiteSpace = false;
19
20    // テスト用のXML文字列を定義します。
21    // DTD (Document Type Definition) 内で 'myEntity' という名前の内部エンティティを定義し、
22    // 日本語の特殊文字を含む文字列をその値として与えます。
23    // ドキュメント自体のエンコーディングはUTF-8と指定しています。
24    $xmlString = <<<XML
25<?xml version="1.0" encoding="UTF-8"?>
26<!DOCTYPE root [
27  <!ENTITY myEntity "こんにちは！エンコーディングテスト">
28  <!ENTITY anotherEntity SYSTEM "nonexistent.ent"> <!-- 外部エンティティの例 (存在しなくても良い) -->
29]>
30<root>
31  <element>&myEntity;</element>
32  <other>&anotherEntity;</other>
33</root>
34XML;
35
36    // XML文字列をDOMDocumentにロードします。
37    // 成功した場合はtrue、失敗した場合はfalseを返します。
38    if (!$dom->loadXML($xmlString)) {
39        echo "エラー: XMLのロードに失敗しました。\n";
40        return;
41    }
42
43    // ドキュメントタイプ (DTD) がXML内に存在するか確認します。
44    // DTDはエンティティを定義するために必要です。
45    if ($dom->doctype === null) {
46        echo "情報: XML内にドキュメントタイプ (DTD) が見つかりませんでした。\n";
47        return;
48    }
49
50    // ドキュメントタイプから定義されているエンティティのリストを取得します。
51    // $dom->doctype->entities は DOMNamedNodeMap を返します。
52    $entities = $dom->doctype->entities;
53
54    if ($entities->length === 0) {
55        echo "情報: DTD内にエンティティが見つかりませんでした。\n";
56        return;
57    }
58
59    echo "--- DOMEntity::actualEncoding プロパティのデモンストレーション ---\n";
60
61    // 各エンティティをループして、その詳細と actualEncoding の値を出力します。
62    foreach ($entities as $entity) {
63        // DOMNamedNodeMap の要素は DOMNode 型ですが、DTDのエンティティは DOMEntity 型であることが保証されます。
64        if ($entity instanceof DOMEntity) {
65            echo "エンティティ名: " . $entity->nodeName . "\n";
66            echo "  ノード値 (内容): " . $entity->nodeValue . "\n";
67
68            // actualEncoding プロパティは、エンティティの実際のエンコーディングを返します。
69            // 内部エンティティの場合、通常はドキュメントのエンコーディング (ここでは UTF-8) となります。
70            // エンコーディングが不明な場合は null を返す可能性があります。
71            echo "  実際のエンコーディング: " . ($entity->actualEncoding ?? '不明 (null)') . "\n\n";
72        }
73    }
74
75    echo "--------------------------------------------------------\n";
76}
77
78// 上記で定義した関数を実行し、サンプルコードの動作を確認します。
79demonstrateDomEntityActualEncoding();
80

DOMEntity::actualEncodingプロパティは、PHPでXMLドキュメントを操作する際に、エンティティの実際のエンコーディング（文字コード）を取得するために使用されます。DOMEntityクラスは、XMLドキュメントオブジェクトモデル（DOM）において、エンティティ（例えば、 のような特殊文字参照や、再利用可能なテキストブロックを定義する仕組み）を表すノードです。

このプロパティは引数を取りません。戻り値はstring型でエンコーディング名（例: "UTF-8"）を返しますが、エンコーディング情報が不明な場合や適用できない場合はnullを返します。

サンプルコードでは、まずDOMDocumentオブジェクトを作成し、テスト用のXML文字列をロードしています。このXMLには、DTD（Document Type Definition）内でmyEntityという内部エンティティが定義されており、ドキュメントのエンコーディングはUTF-8と指定されています。コードは、ロードされたXMLからdoctype情報を取得し、その中に含まれるエンティティのリストを巡回します。

各エンティティに対して、$entity->actualEncodingのようにプロパティにアクセスすることで、そのエンティティが使用している実際のエンコーディング情報を取得し、表示します。内部エンティティの場合、通常はドキュメント自身のエンコーディングが返されます。このように、XMLドキュメント内のエンティティがどのような文字コードで表現されているかを確認できるため、異なるエンコーディングを持つXMLファイルを扱う際に、文字化けを防ぐための適切な処理を行う判断材料として活用できます。

Copy
1<?php
2
3/**
4 * DOMEntity::actualEncoding プロパティの使用例を示します。
5 *
6 * この関数は、異なるエンコーディングの外部エンティティファイルを作成し、
7 * それを参照するXMLドキュメントをDOMとしてロードします。
8 * その後、ロードされたDOMから DOMEntity オブジェクトを取得し、
9 * actualEncoding プロパティがどのように外部エンティティのエンコーディングを示すかを実演します。
10 *
11 * DOMEntity::actualEncoding は、外部パース済みエンティティ（外部ファイルから読み込まれるエンティティ）が
12 * 実際に使用しているエンコーディングを返します。
13 * これは、エンコーディングの検出や変換のシナリオを理解する上で役立ちます。
14 */
15function demonstrateDOMEntityActualEncoding(): void
16{
17    // 1. 外部エンティティファイルをShift-JISエンコーディングで作成します。
18    //    PHPのmb_convert_encodingを使って、UTF-8の文字列をShift-JISに変換してファイルに書き込みます。
19    $entityFileName = 'external_entity.txt';
20    $originalContent = "こんにちは、PHPエンコーディング！";
21    $sjisContent = mb_convert_encoding($originalContent, 'SJIS', 'UTF-8');
22    file_put_contents($entityFileName, $sjisContent);
23
24    echo "--- 準備フェーズ ---\n";
25    echo "外部エンティティファイル '{$entityFileName}' をShift-JISで作成しました。\n";
26    echo "ファイルサイズ: " . filesize($entityFileName) . "バイト\n\n";
27
28    // 2. 作成した外部エンティティを参照するXMLドキュメントを作成します。
29    //    このXML自体はUTF-8でエンコードされています。
30    $xmlFileName = 'document_with_entity.xml';
31    $xmlContent = <<<XML
32<?xml version="1.0" encoding="UTF-8"?>
33<!DOCTYPE root [
34  <!ENTITY myExternalEntity SYSTEM "{$entityFileName}">
35  <!ENTITY myInternalEntity "内部エンティティ">
36]>
37<root>
38  <message>&myExternalEntity;</message>
39  <note>&myInternalEntity;</note>
40</root>
41XML;
42    file_put_contents($xmlFileName, $xmlContent);
43
44    echo "XMLドキュメント '{$xmlFileName}' を作成しました。\n";
45    echo "XMLコンテンツ:\n{$xmlContent}\n";
46    echo "--------------------\n\n";
47
48    // 3. XMLドキュメントをDOMとしてロードします。
49    $dom = new DOMDocument();
50    // 外部エンティティのロードを許可する設定を有効にします。
51    $dom->substituteEntities = true;
52    // XMLファイルをロードします。@を付けてDTD関連の警告を抑制することがあります。
53    @$dom->load($xmlFileName);
54
55    echo "--- DOM解析結果 ---\n";
56
57    // DOMDocumentType (DTD) が存在し、エンティティが定義されているかを確認します。
58    if ($dom->doctype && $dom->doctype->entities) {
59        echo "ロードされたXMLドキュメントのエンティティ情報:\n";
60
61        // DOMNamedNodeMap を反復処理して、定義されているすべてのエンティティを取得します。
62        foreach ($dom->doctype->entities as $entity) {
63            // エンティティが DOMEntity クラスのインスタンスであることを確認します。
64            if ($entity instanceof DOMEntity) {
65                echo "----------------------------------------\n";
66                echo "エンティティ名: " . $entity->nodeName . "\n";
67
68                // actualEncoding プロパティは、外部エンティティがどのエンコーディングで定義されているかを示します。
69                // 内部エンティティの場合、通常は null またはドキュメントのエンコーディングが返されます。
70                echo "actualEncoding: " . ($entity->actualEncoding ?? 'null (または未定義)') . "\n";
71
72                // nodeValue は、DOMが内部的にエンコーディングを処理した後のエンティティの内容です。
73                // 通常、ドキュメントのエンコーディング（この例ではUTF-8）に変換されています。
74                echo "nodeValue (内容): " . $entity->nodeValue . "\n";
75
76                // systemId は外部エンティティの場合、そのファイルのパスを示します。
77                echo "systemId (外部エンティティのパス): " . ($entity->systemId ?? 'null') . "\n";
78            }
79        }
80        echo "----------------------------------------\n";
81    } else {
82        echo "XMLドキュメントにDTDまたはエンティティが見つかりませんでした。\n";
83    }
84
85    // 4. 作成した一時ファイルをクリーンアップします。
86    unlink($entityFileName);
87    unlink($xmlFileName);
88    echo "\n--- クリーンアップ ---\n";
89    echo "一時ファイル '{$entityFileName}' と '{$xmlFileName}' を削除しました。\n";
90    echo "--------------------\n";
91}
92
93// 関数を実行して、DOMEntity::actualEncoding の動作を確認します。
94demonstrateDOMEntityActualEncoding();
95
96?>

DOMEntity::actualEncodingは、XMLドキュメントの外部パース済みエンティティが実際に使用しているエンコーディングを文字列で取得するプロパティです。引数はなく、エンコーディング名（string）またはnullを返します。nullは、エンコーディングが特定できない場合や、内部エンティティである場合に返されます。

このサンプルコードは、DOMEntity::actualEncodingプロパティの動作を実演します。まず、Shift-JISでエンコードされたテキストファイル（外部エンティティ）を作成します。次に、この外部エンティティと内部エンティティを参照するXMLドキュメントを作成し、DOMDocumentクラスでロードします。DOMDocumentは外部エンティティをロードする際に、そのエンコーディングを自動的に検出します。

ロード後、XMLのDOCTYPEから取得した各DOMEntityオブジェクトに対してactualEncodingプロパティを参照します。作成した外部エンティティに対しては、actualEncodingがSJISと表示され、実際にファイルがShift-JISでエンコードされていることを示します。一方、XML内で直接定義された内部エンティティの場合、このプロパティはnullを返します。nodeValueは、DOMが内部で処理し、通常はドキュメントのエンコーディングに変換された後の内容を示します。これにより、外部リソースのエンコーディング情報を効率的に取得できることがわかります。