【PHP8.x】libxml_set_external_entity_loader()関数の使い方
libxml_set_external_entity_loader関数の使い方について、初心者にもわかりやすく解説します。
基本的な使い方
libxml_set_external_entity_loader関数は、PHPがXMLドキュメント内の外部エンティティを読み込む方法をカスタマイズするためのコールバック関数を設定する関数です。
XMLドキュメントは、文書型定義(DTD)や外部XMLファイルなど、別の場所の情報を参照することがあり、これらを「外部エンティティ」と呼びます。通常PHPは、これらの外部エンティティを自動的に読み込みます。
この関数を使用すると、開発者は独自のコールバック関数を登録し、外部エンティティが参照された際にその関数が呼び出されるように設定できます。これにより、PHPのデフォルトの読み込み動作を上書きし、外部リソースへのアクセスを細かく制御することが可能になります。例えば、セキュリティ上の理由で特定のファイルパスからの読み込みを制限したり、あるいはデータベースなどカスタムのデータソースからエンティティのデータを取得したりといった柔軟な処理を実現できます。
設定するコールバック関数は、XMLパーサーから渡される引数を受け取り、外部エンティティのデータを提供するストリームリソースを返すか、処理できない場合はfalseを返す必要があります。この機能は強力ですが、悪意のあるXMLドキュメントによるXML外部エンティティ攻撃(XXE攻撃)を防ぐためにも、信頼できないXMLを処理する際には、セキュリティに十分な注意を払って利用することが極めて重要です。この関数は、以前設定されていたエンティティローダー関数を返します。
構文(syntax)
1<?php 2libxml_set_external_entity_loader(function (string $publicId, string $systemId, string $baseUri, string $userData) { 3 // 外部エンティティを処理するロジックをここに記述します。 4 // null を返すと、デフォルトのエンティティローダーが呼び出されます。 5 return null; 6}); 7?>
引数(parameters)
?callable $resolver_function = null
- callable $resolver_function: 外部エンティティを解決するためのコールバック関数。
nullを指定すると、libxml はデフォルトのエンティティ解決メカニズムを使用します。
戻り値(return)
void
この関数は、外部エンティティ(XML文書の外部にあるリソース)を読み込むためのコールバック関数を設定するために使用されます。設定が成功したかどうかにかかわらず、戻り値はありません。
サンプルコード
PHP: libxml_set_external_entity_loader で外部エンティティを制御する
1<?php 2 3/** 4 * 外部エンティティの解決とXMLエラー処理の例。 5 * 6 * このスクリプトは、外部エンティティを参照するXMLをパースする際に、 7 * libxml_set_external_entity_loader を使用して外部エンティティの読み込みをカスタマイズし、 8 * libxml_use_internal_errors を使用してXMLパースエラーを捕捉する方法を示します。 9 */ 10 11// libxml_use_internal_errors を有効にし、XMLパースエラーを内部で捕捉するように設定します。 12// これにより、デフォルトの警告やエラー出力が抑制され、libxml_get_errors() でエラー情報にアクセスできるようになります。 13libxml_use_internal_errors(true); 14 15// libxml_set_external_entity_loader を使用して、外部エンティティの解決方法をカスタマイズするコールバック関数を設定します。 16// このコールバックは、XMLパーサーが外部エンティティ(例: DTDのSYSTEMエンティティ)を解決しようとしたときに呼び出されます。 17libxml_set_external_entity_loader(function (string $publicId, string $systemId, array $context): ?string { 18 echo "外部エンティティの解決を試行中: systemId='{$systemId}', publicId='{$publicId}'\n"; 19 20 // ここで、$systemId や $publicId に基づいて外部リソース(ファイル、URLなど)を読み込み、その内容を文字列で返します。 21 // この例では、特定のsystemIdに対して固定の文字列を返します。 22 if ($systemId === 'my_external_resource.txt') { 23 return 'これはカスタマイズされた外部エンティティの内容です。'; 24 } 25 26 // 未知の外部エンティティの場合はnullを返し、libxmlのデフォルトの解決処理に任せるか、エラーとして処理させます。 27 return null; 28}); 29 30// 外部エンティティを参照するXML文字列を定義します。 31// <!ENTITY myEntity SYSTEM "my_external_resource.txt"> で外部エンティティを宣言し、 32// &myEntity; でその内容を参照しています。 33$xmlString = <<<XML 34<?xml version="1.0" encoding="UTF-8"?> 35<!DOCTYPE root [ 36 <!ENTITY myEntity SYSTEM "my_external_resource.txt"> 37]> 38<root> 39 <data>外部エンティティの内容: &myEntity;</data> 40 <otherData>これは別のデータです。</otherData> 41</root> 42XML; 43 44// DOMDocumentオブジェクトを作成します。 45$dom = new DOMDocument(); 46 47// XML文字列をロードします。 48// LIBXML_NOENT フラグは、外部エンティティを展開するために必要です。 49// これがないと、&myEntity; は展開されずにそのまま残る可能性があります。 50echo "\nXML文字列のロードを試行中...\n"; 51if ($dom->loadXML($xmlString, LIBXML_NOENT)) { 52 echo "XMLは正常にロードされ、エンティティは展開されました。\n"; 53 echo "結果のXML:\n"; 54 // saveXML() で整形されたXMLを出力します。 55 echo $dom->saveXML(); 56} else { 57 echo "XMLのロードに失敗しました。\n"; 58} 59 60// libxml_get_errors() を使用して、捕捉されたすべてのXMLエラーを取得し表示します。 61$errors = libxml_get_errors(); 62if (!empty($errors)) { 63 echo "\n検出されたXMLエラー:\n"; 64 foreach ($errors as $error) { 65 // エラーのレベル(警告、エラー、致命的エラーなど)、メッセージ、行番号などを表示します。 66 echo " [レベル {$error->level}] {$error->message} (行: {$error->line}, 列: {$error->column})\n"; 67 } 68} else { 69 echo "\nXMLエラーは検出されませんでした。\n"; 70} 71 72// libxml_clear_errors() を使用して、libxmlのエラーバッファをクリアします。 73// これは、後続のXML処理で以前のエラーが混在しないようにするために重要です。 74libxml_clear_errors(); 75 76// 外部エンティティローダーを解除する場合 (オプション): 77// libxml_set_external_entity_loader(null); 78?>
このPHPコードは、XML文書が参照する外部エンティティの読み込み方法を独自に制御し、XMLパース時に発生するエラーを効率的に処理する例です。
まず、libxml_use_internal_errors(true)を使用することで、XMLの解析中に発生する警告やエラーがPHPの内部に蓄積され、スクリプトの実行を中断することなく、後から詳細なエラー情報を取得できるようになります。
次に、libxml_set_external_entity_loader関数は、XMLパーサーが外部エンティティ(例えば、DTDで指定された外部ファイルなど)を読み込もうとしたときに、どのような処理を行うかをカスタマイズするためのものです。この関数には、引数として外部エンティティの解決ロジックを実装したコールバック関数を渡します。このコールバック関数は、解決対象のエンティティに関する情報(公開ID、システムIDなど)を受け取り、その内容を文字列として返すか、デフォルトの解決処理に任せる場合はnullを返します。このlibxml_set_external_entity_loader関数の戻り値はvoidで、設定が成功したことを示します。
サンプルコードでは、特定のシステムIDを持つ外部エンティティに対して、あらかじめ決められた文字列を返すように設定しています。DOMDocument::loadXMLでXMLを読み込む際にLIBXML_NOENTフラグを指定すると、このカスタマイズされた外部エンティティの内容がXML文書内に展開されます。
最後に、libxml_get_errors()関数を使って、これまでに捕捉されたすべてのXMLエラーを取得し、その詳細を表示しています。処理の終了後にはlibxml_clear_errors()を呼び出すことで、次のXML処理に影響を与えないように、エラーバッファをクリアすることが推奨されます。これらの機能により、外部リソースと連携するXML処理をより堅牢に制御できます。
外部エンティティのカスタムローダーは、XML External Entity (XXE) 攻撃のようなセキュリティリスクにつながるため、信頼できないXMLデータに適用する際は、入力検証とリソースアクセス制御を厳重に行い、情報漏洩や不正なファイル読み込みを防ぐことが非常に重要です。コールバック関数は、渡されるsystemIdなどを必ず検証してください。また、libxml_use_internal_errors(true)はXMLパースエラーを捕捉するために必須の設定で、これがないと警告が表示されるだけでエラーをプログラムで処理できません。XMLの外部エンティティを展開するには、DOMDocument::loadXMLなどの関数にLIBXML_NOENTフラグを指定する必要があります。この設定はPHPプロセス全体に影響するため、不要になったらnullを渡して解除することを検討してください。
PHP libxml 外部エンティティローダー設定
1<?php 2 3// libxml_set_external_entity_loader関数のサンプルコード 4// この関数は、libxmlがXML内の外部エンティティ(例: DTDファイル)を解決する際の挙動をカスタマイズします。 5// 主に、セキュリティ強化のために外部リソースへのアクセスを制御したり、 6// データベースなどカスタムの場所からエンティティをロードしたりする際に使用されます。 7 8// 1. 外部DTDを参照するXML文字列を定義します。 9// ここでは、"my-custom-dtd.dtd" というSYSTEM識別子を持つDTDを参照しています。 10$xmlString = <<<XML 11<!DOCTYPE document SYSTEM "my-custom-dtd.dtd"> 12<document> 13 <element>Hello XML!</element> 14</document> 15XML; 16 17// 2. 外部エンティティとして解決するDTDの内容を文字列として定義します。 18// 通常、この内容は外部ファイルから読み込まれるものですが、ここでは例として直接定義します。 19$dtdContent = <<<DTD 20<!ELEMENT document (element)> 21<!ELEMENT element (#PCDATA)> 22DTD; 23 24// 3. libxml_set_external_entity_loaderに渡すコールバック関数を定義します。 25// この関数は、libxmlがXML内のSYSTEM識別子やPUBLIC識別子を解決しようとしたときに呼び出されます。 26// `use ($dtdContent)` を使うことで、この匿名関数内で外部の `$dtdContent` 変数にアクセスできるようになります。 27$resolver = function (string $publicId, string $systemId, array $context) use ($dtdContent): ?resource { 28 // $publicId: エンティティのパブリックID(通常は空文字列) 29 // $systemId: エンティティのシステムID(ファイルパスやURLなど、今回の例では "my-custom-dtd.dtd") 30 // $context: libxmlのコンテキスト情報(libxml_context リソース) 31 32 // どのSystem IDの解決が試みられているかを出力します(デバッグ用)。 33 echo "Attempting to resolve external entity with System ID: '{$systemId}'\n"; 34 35 // ここでカスタムの解決ロジックを実装します。 36 // 今回は、特定のSystem ID ("my-custom-dtd.dtd") が来た場合に、 37 // 事前に定義したDTDの内容をメモリから提供するようにします。 38 if ($systemId === "my-custom-dtd.dtd") { 39 // メモリ内の文字列から読み取り可能なリソース(ファイルポインタ)を作成します。 40 // `php://memory`ストリームを使い、DTD文字列を書き込んでから、その先頭にポインタを戻します。 41 $handle = fopen('php://memory', 'r+'); 42 if ($handle === false) { 43 echo "Error: Failed to open php://memory stream for DTD.\n"; 44 return false; // ストリームが開けない場合は解決失敗として報告 45 } 46 fwrite($handle, $dtdContent); // 定義済みのDTDコンテンツをメモリに書き込み 47 fseek($handle, 0); // ポインタをファイルの先頭に戻し、読み込み準備完了 48 return $handle; // 解決されたリソースを返します 49 } 50 51 // 上記で対応しないSystem IDは解決をブロックします。 52 // これは、未知の外部リソースへのアクセスを防ぐセキュリティ対策として重要です。 53 echo "Blocked resolution for unknown System ID: '{$systemId}'\n"; 54 return false; // libxmlにこのエンティティを解決させないことを通知します 55}; 56 57// 4. 定義したコールバック関数をlibxmlの外部エンティティローダーとして登録します。 58libxml_set_external_entity_loader($resolver); 59 60// libxmlのエラーを内部で捕捉し、エラー情報を取得できるように設定します。 61libxml_use_internal_errors(true); 62libxml_clear_errors(); // 以前のエラーが残っている可能性があるのでクリアします 63 64// 5. DOMDocumentを使用してXMLをロードし、DTD検証を行います。 65$dom = new DOMDocument(); 66$dom->validateOnParse = true; // XMLパース時にDTD検証を有効にします 67 68if ($dom->loadXML($xmlString)) { 69 echo "XML loaded successfully.\n"; 70 if ($dom->validate()) { 71 echo "XML is valid according to DTD resolved by custom loader.\n"; 72 } else { 73 echo "XML validation failed.\n"; 74 // 検証失敗時にlibxmlが捕捉したエラーメッセージを表示します 75 foreach (libxml_get_errors() as $error) { 76 echo "LIBXML Error (" . $error->code . "): " . trim($error->message) . " at line " . $error->line . "\n"; 77 } 78 } 79} else { 80 echo "Failed to load XML.\n"; 81 // XMLロード失敗時にlibxmlが捕捉したエラーメッセージを表示します 82 foreach (libxml_get_errors() as $error) { 83 echo "LIBXML Error (" . $error->code . "): " . trim($error->message) . " at line " . $error->line . "\n"; 84 } 85} 86 87// 6. 使用後、外部エンティティローダーをデフォルトの状態にリセットします。 88// これは、他のXML処理に影響を与えないための良い習慣です。 89libxml_set_external_entity_loader(null); 90 91// libxmlエラー設定を元に戻します(オプション)。 92libxml_use_internal_errors(false); 93 94?>
libxml_set_external_entity_loader関数は、PHPがXMLを解析する際に、外部エンティティ(例えばDTDファイル)の読み込み方を制御するものです。これにより、外部リソースへのアクセスを制限してセキュリティを高めたり、ファイルシステム以外の場所からエンティティを読み込んだりすることが可能になります。
引数$resolver_functionには、外部エンティティを解決するためのコールバック関数を指定します。XMLパーサーが外部エンティティの参照を見つけると、この関数が自動的に呼び出され、エンティティのSystem IDなどの情報を受け取ります。コールバック関数は、対応するコンテンツをファイルリソースとして返すか、解決を拒否するためにfalseを返します。引数にnullを設定するとローダーはデフォルト動作に戻り、戻り値はvoidです。
サンプルコードでは、my-custom-dtd.dtdを参照するXMLを検証する例で、カスタムローダーの利用方法を示しています。コールバック関数内で、特定のDTDの内容をメモリ(php://memoryストリーム)から提供することで、ファイルが存在しなくてもXMLの検証を可能にしています。また、未知のSystem IDからの要求はブロックし、セキュリティリスクを低減する対策も示しています。処理後は、ローダーをデフォルトに戻すことが推奨されます。
この関数は、XMLが外部エンティティを参照する際の挙動をカスタマイズし、特にセキュリティ強化のために重要です。コールバック関数内では、許可されたSystem ID以外は必ず解決をブロックするよう実装し、未知の外部リソースへのアクセスを厳しく制限してください。また、カスタムローダーを一度設定すると、その後の全てのXML処理に影響を及ぼしますので、処理が完了したらlibxml_set_external_entity_loader(null)を呼び出して、デフォルトの挙動にリセットするのを忘れないように注意してください。コールバック関数で外部変数を利用する際はuseキーワードが必要となる点も押さえておきましょう。