【PHP8.x】DOMEntityReference::localNameプロパティの使い方

localNameプロパティの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月11日

基本的な使い方

localNameプロパティは、DOMエンティティ参照のローカル名を保持するプロパティです。DOMは、HTMLやXML文書の構造をプログラムから操作するための仕組みであり、DOMEntityReferenceクラスは文書内で使用されるエンティティ参照（例: & や ©）を表します。このプロパティにアクセスすると、そのエンティティ参照の名前を文字列として取得することが可能です。具体的には、XML文書内に &example; というエンティティ参照が存在する場合、それに対応するDOMEntityReferenceオブジェクトのlocalNameプロパティを参照すると、"example" という文字列が返されます。このプロパティは、XML名前空間で定義された接頭辞（プレフィックス）を含まない、ノード本来の名前を返すという特徴を持っています。DOMEntityReferenceノードの場合、localNameプロパティが返す値はnodeNameプロパティが返す値と同じになります。なお、このプロパティは読み取り専用であるため、localNameプロパティに値を代入してエンティティ参照の名前を後から変更することはできません。

構文(syntax)


1<?php
2
3$xml = <<<XML
4<?xml version="1.0" encoding="utf-8"?>
5<!DOCTYPE root [
6<!ENTITY myEntity "entity text">
7]>
8<root>
9  <child>&myEntity;</child>
10</root>
11XML;
12
13$dom = new DOMDocument();
14$dom->loadXML($xml);
15
16// <child>要素内のエンティティ参照ノードを取得
17$entityReferenceNode = $dom->getElementsByTagName('child')->item(0)->firstChild;
18
19// DOMEntityReference オブジェクトの localName プロパティを取得します。
20// これは名前空間プレフィックスを除いたエンティティ名（この場合は "myEntity"）を返します。
21$localName = $entityReferenceNode->localName;
22
23var_dump($localName);
24
25?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

string|null

DOMEntityReference オブジェクトで参照されているエンティティのローカル名を文字列で返します。ローカル名が取得できない場合は null を返します。

サンプルコード

DOMEntityReference::localName を取得する


1<?php
2
3/**
4 * DOMEntityReference::localName プロパティの使用例を示します。
5 *
6 * この関数は、XML ドキュメントにエンティティ参照ノードを手動で作成・追加し、
7 * その localName プロパティを取得します。
8 * localName は、名前空間プレフィックスを含まないノードのローカル名です。
9 * DOMEntityReference の場合、これは通常エンティティの名前自体になります。
10 */
11function demonstrateDomEntityReferenceLocalName(): void
12{
13    // 新しい DOMDocument オブジェクトを作成します。
14    // XML バージョン1.0、エンコーディングUTF-8を指定します。
15    $dom = new DOMDocument('1.0', 'UTF-8');
16    // 生成されるXML出力を見やすくするためにフォーマットを有効にします。
17    $dom->formatOutput = true;
18
19    // ルート要素として 'document' という名前の要素を作成し、ドキュメントに追加します。
20    $root = $dom->createElement('document');
21    $dom->appendChild($root);
22
23    // 'myEntityRef' という名前のエンティティ参照ノードを作成します。
24    // ここで指定する文字列が、このエンティティ参照の「名前」となります。
25    $entityRef = $dom->createEntityReference('myEntityRef');
26
27    // 作成したエンティティ参照ノードを、ルート要素の子として追加します。
28    $root->appendChild($entityRef);
29
30    // DOMEntityReference オブジェクトの localName プロパティを取得します。
31    // エンティティ参照には通常名前空間が適用されないため、
32    // localName プロパティは nodeName (エンティティの名前) と同じ値になります。
33    $localName = $entityRef->localName;
34
35    echo "DOMEntityReference::localName のデモンストレーション:\n";
36    echo "---------------------------------------------------\n";
37    echo "作成されたエンティティ参照ノードの nodeName: " . $entityRef->nodeName . "\n";
38    echo "取得された localName プロパティの値: " . ($localName ?? 'null') . "\n";
39    echo "---------------------------------------------------\n";
40    echo "生成されたXMLドキュメント:\n";
41    echo $dom->saveXML();
42}
43
44// 関数を実行して、DOMEntityReference::localName の動作を確認します。
45demonstrateDomEntityReferenceLocalName();
46

PHPのDOMEntityReference::localNameプロパティは、XMLドキュメント内でエンティティ参照ノードの「ローカル名」を取得するために使用されます。ローカル名とは、XML名前空間のプレフィックスを含まない、ノード本来の名前部分を指します。DOMEntityReferenceの場合、エンティティ参照は通常名前空間を持たないため、このlocalNameプロパティはエンティティの名前（nodeNameプロパティと同じ値）そのものとなります。

このプロパティには引数はなく、ノードのローカル名を文字列として返します。もしローカル名が存在しない場合や適用されない場合はnullを返します。

提供されたサンプルコードでは、まず新しいDOMDocumentオブジェクトを作成し、ルート要素とその子として'myEntityRef'という名前のエンティティ参照ノードを手動で作成し追加しています。その後、作成したDOMEntityReferenceオブジェクトのlocalNameプロパティにアクセスし、その値を取得・表示しています。実行すると、'myEntityRef'というエンティティ参照のlocalNameもまた'myEntityRef'として出力されることが確認できます。これは、エンティティ参照のローカル名が、エンティティそのものの名前と一致することを示しています。

localNameプロパティは、ノードの名前空間プレフィックスを除いた名前を指します。DOMEntityReferenceの場合、通常名前空間を持たないため、nodeNameプロパティとほぼ同じ値になることを理解しておくと良いでしょう。このサンプルではプログラムでエンティティ参照を作成していますが、実際のXML処理では、DTD（Document Type Definition）などで定義されたエンティティを参照する際に用いられることが一般的です。そのため、エンティティの定義がないXMLに対して利用すると期待通りに動作しない場合があります。localNameの戻り値は文字列かnullの可能性があるため、値を利用する際はnullチェックを行うと、より安全なコードになります。このプロパティは読み取り専用であり、値を直接変更することはできません。

PHP DOMEntityReference::localName を取得する


1<?php
2
3/**
4 * DOMEntityReference::localName プロパティのデモンストレーション。
5 *
6 * このスクリプトは、PHPの組み込みウェブサーバーやローカル環境 (XAMPP/MAMPなど) で
7 * 実行することを想定しています。ウェブブラウザでこのファイルにアクセスすると、結果が表示されます。
8 */
9function demonstrateDomEntityReferenceLocalName(): void
10{
11    // DOMDocument オブジェクトを作成します。
12    // これはXMLドキュメントを扱うための基本となるクラスです。
13    $dom = new DOMDocument();
14
15    // 'amp' という名前の実体参照を表す DOMEntityReference オブジェクトを作成します。
16    // 'amp' は '&amp;' と記述される、XMLの標準的な実体（アンパサンド）を指します。
17    // このプロパティの値を直接確認するため、ここではオブジェクトを明示的に生成しています。
18    $entityRef = $dom->createEntityReference('amp');
19
20    // DOMEntityReference::localName プロパティは、実体参照のローカル名を返します。
21    // 'amp' という名前で作成したので、ここでは 'amp' という文字列が返されるはずです。
22    $localName = $entityRef->localName;
23
24    echo "<h1>DOMEntityReference::localName のデモンストレーション</h1>\n";
25    echo "<p>作成された実体参照のローカル名: <strong>" . htmlspecialchars($localName) . "</strong></p>\n";
26    echo "<p>これは、XMLの実体参照 '&amp;' の 'amp' 部分に相当します。</p>\n";
27
28    // 別のカスタム実体参照の例も見てみましょう。
29    // 例えば、XMLのDTD（文書型定義）で定義されることのあるカスタム実体名 'myEntity' の場合:
30    $customEntityRef = $dom->createEntityReference('myEntity');
31    $customLocalName = $customEntityRef->localName;
32    echo "<p>カスタム実体参照 ('myEntity') のローカル名: <strong>" . htmlspecialchars($customLocalName) . "</strong></p>\n";
33}
34
35// 関数を実行して、ブラウザに結果を表示します。
36demonstrateDomEntityReferenceLocalName();

このPHPコードは、XMLドキュメント内で実体参照を扱うDOMEntityReferenceクラスのlocalNameプロパティの働きを具体的に示しています。DOMEntityReferenceは、&のようなXMLの実体参照（エンティティ参照）を表すオブジェクトです。

localNameプロパティは、この実体参照の「ローカル名」と呼ばれる部分を取得するために使われます。これは実体参照の名前そのものに相当し、例えば&であればamp、&myEntity;であればmyEntityがローカル名です。このプロパティに引数を渡す必要はありません。

サンプルコードでは、まずDOMDocumentオブジェクトを使って'amp'という名前の実体参照を作成しています。そして、そのlocalNameプロパティを参照すると、期待通り"amp"という文字列が取得される様子が示されています。さらに、カスタムの実体参照として'myEntity'を作成した場合でも、"myEntity"がローカル名として正しく取得されることが確認できます。

localNameプロパティの戻り値は、通常、実体参照のローカル名を表す文字列ですが、場合によってはnullが返されることもあります。このコードは、初心者の方でもPHPの組み込みウェブサーバーやXAMPPなどのローカル環境で簡単に実行し、結果をブラウザで確認できるようになっています。

このサンプルコードはPHPのDOM拡張機能が有効な環境で動作します。DOMDocumentなどのクラスが利用できない場合は、PHP設定（php.ini）でDOM拡張が有効になっているか確認してください。

DOMEntityReference::localNameは、XMLの実体参照名（例: & の amp）を取得するプロパティです。サンプルではcreateEntityReferenceでオブジェクトを生成していますが、これは実際にXMLドキュメントに挿入される前段階で、オブジェクトのプロパティ単体を検査している点にご留意ください。

特に重要なのは、echoで出力する際にhtmlspecialchars()を使用している点です。これにより、取得した文字列がHTMLとして解釈されず、画面に安全に表示されます。これは、悪意のあるスクリプトの埋め込み（XSS）を防ぐためのセキュリティ対策として、ウェブアプリケーション開発において常に意識すべき基本的な手法です。