【PHP8.x】Dom\Entity::cloneNode()メソッドの使い方

cloneNodeメソッドの使い方について、初心者にもわかりやすく解説します。

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

基本的な使い方

『cloneNodeメソッドは、呼び出し元であるDom\Entityオブジェクトの複製を作成するメソッドです。このメソッドは、XMLドキュメント内のエンティティ（実体）を表すノードをコピーし、新しいノードとして生成する際に使用します。引数としてbool型の値を渡すことができ、trueを指定するとノードとその子孫をすべて再帰的に複製するディープクローンを、falseを指定するか省略した場合はノード自身のみを複製するシャロークローンを実行します。しかし、Dom\Entityノードは仕様上子ノードを持つことができないため、このメソッドにおいて引数の値は複製結果に影響を与えません。どちらの場合も、エンティティノード自体が複製されます。メソッドの実行が成功すると、複製された新しいDom\Nodeオブジェクトが返されます。複製されたノードは、元のドキュメントツリーには属しておらず、親ノードを持たない独立した状態です。そのため、ドキュメントに組み込むにはappendChildなどのメソッドを別途呼び出す必要があります。もし何らかの理由で複製に失敗した場合は、falseが返されます。』

構文(syntax)


1<?php
2
3$xml = '<!DOCTYPE doc [<!ENTITY greeting "Hello">]><doc/>';
4$document = new DOMDocument();
5$document->loadXML($xml);
6
7// 複製元のエンティティノードを取得
8$originalEntity = $document->doctype->entities->getNamedItem('greeting');
9
10// エンティティノードのコピーを作成する
11// 引数に true を指定すると、再帰的に子孫もすべてコピーします
12$clonedEntity = $originalEntity->cloneNode(true);
13
14// 複製されたノードの名前を出力
15echo $clonedEntity->nodeName;

引数(parameters)

bool $deep = false

bool $deep = false: trueを指定すると、ノードとそのすべての子孫ノードが複製されます。falseを指定すると、ノードのみが複製され、子ノードは複製されません。

戻り値(return)

Dom\Node|false

指定された Dom\Entity オブジェクトのノードのディープコピーを返します。コピーに失敗した場合は false を返します。

サンプルコード

PHP Dom\Entity::cloneNode でエンティティをクローンする


1<?php
2
3// このコードは Dom\Entity::cloneNode メソッドの動作を示します。
4// Dom\Entity は XML DTD (Document Type Definition) で定義されたエンティティを表します。
5// Dom\Entity オブジェクト自体は子ノードを持たないため、
6// cloneNode() メソッドの $deep 引数 (true/false) の違いは結果に現れません。
7
8// DTD を含む XML 文字列を定義し、DOMDocument にロードします。
9$xmlString = <<<XML
10<!DOCTYPE root [
11  <!ENTITY myEntity "これは私のエンティティです。">
12]>
13<root>
14  &myEntity;
15</root>
16XML;
17
18$dom = new DOMDocument();
19// XML文字列をロードし、DTDを解析します。
20$dom->loadXML($xmlString);
21
22// ドキュメントタイプ (DTD情報) を取得します。
23$documentType = $dom->doctype;
24
25if (!$documentType) {
26    echo "エラー: ドキュメントタイプ (DTD) が見つかりません。" . PHP_EOL;
27    exit(1);
28}
29
30// DTDから 'myEntity' という名前の Dom\Entity オブジェクトを取得します。
31$originalEntity = $documentType->entities->getNamedItem('myEntity');
32
33if ($originalEntity instanceof Dom\Entity) {
34    echo "--- 元の Dom\\Entity オブジェクト ---" . PHP_EOL;
35    echo "ノード名: " . $originalEntity->nodeName . PHP_EOL; // エンティティ名 (例: myEntity)
36    echo "ノードタイプ: " . $originalEntity->nodeType . " (ENTITY_NODE)" . PHP_EOL; // Dom\Node::ENTITY_NODE (6)
37    echo "子ノードの数: " . $originalEntity->childNodes->length . PHP_EOL; // Dom\Entity は子ノードを持たないため、常に0
38    echo PHP_EOL;
39
40    // cloneNode(false) を使用して、元の Dom\Entity を浅くクローンします。
41    // (属性や子ノードはコピーされません。Dom\Entity は子を持たないので実質的に本体のみコピーされます)
42    $shallowClonedEntity = $originalEntity->cloneNode(false);
43
44    echo "--- 浅くクローンされた Dom\\Entity (cloneNode(false)) ---" . PHP_EOL;
45    echo "ノード名: " . $shallowClonedEntity->nodeName . PHP_EOL;
46    echo "ノードタイプ: " . $shallowClonedEntity->nodeType . " (ENTITY_NODE)" . PHP_EOL;
47    echo "子ノードの数: " . $shallowClonedEntity->childNodes->length . PHP_EOL; // 0
48    echo "元のエンティティと同じオブジェクトか？: " . ($originalEntity === $shallowClonedEntity ? "true" : "false") . PHP_EOL; // 新しいオブジェクトなので false
49    echo PHP_EOL;
50
51    // cloneNode(true) を使用して、元の Dom\Entity を深くクローンします。
52    // (属性と子ノードもコピーされますが、Dom\Entity は子を持たないため、浅いクローンとの違いはありません)
53    $deepClonedEntity = $originalEntity->cloneNode(true);
54
55    echo "--- 深くクローンされた Dom\\Entity (cloneNode(true)) ---" . PHP_EOL;
56    echo "ノード名: " . $deepClonedEntity->nodeName . PHP_EOL;
57    echo "ノードタイプ: " . $deepClonedEntity->nodeType . " (ENTITY_NODE)" . PHP_EOL;
58    echo "子ノードの数: " . $deepClonedEntity->childNodes->length . PHP_EOL; // 0
59    echo "元のエンティティと同じオブジェクトか？: " . ($originalEntity === $deepClonedEntity ? "true" : "false") . PHP_EOL; // 新しいオブジェクトなので false
60    echo PHP_EOL;
61
62    echo "※ Dom\\Entity は子ノードを持たないため、" . PHP_EOL;
63    echo "   cloneNode(true) と cloneNode(false) の動作結果に違いはありません。" . PHP_EOL;
64
65} else {
66    echo "エラー: 'myEntity' という名前の Dom\\Entity オブジェクトを見つけることができませんでした。" . PHP_EOL;
67}

PHP 8のDom\Entity::cloneNodeメソッドは、XMLのDTD（Document Type Definition）で定義されたエンティティを表すDom\Entityオブジェクトを複製するために使用されます。このメソッドは、元のエンティティと同じ特性を持つ新しいオブジェクトを作成し、それを返します。

引数$deepは、クローンの深さを指定します。trueを指定すると、ノード自体に加えて子ノードや属性もすべてコピーする「深いクローン」が作成されます。falseを指定すると、ノード自体のみをコピーし、子ノードや属性は含まない「浅いクローン」が作成されます。しかし、Dom\Entityは構造的に子ノードを持たないため、この$deep引数をtrueにしてもfalseにしても、結果として生成されるクローンオブジェクトに実質的な違いは生じません。

メソッドが正常に実行されると、新しくクローンされたDom\Nodeオブジェクト（この場合、Dom\Entityのインスタンス）が返されます。何らかの理由で複製に失敗した場合はfalseが返されます。このcloneNodeメソッドは、PHPのcloneキーワードを使った一般的なオブジェクトの複製とは異なり、DOMツリー内の特定のノードの構造を複製することに特化しています。

このコードは、XMLのDTDで定義される特殊なノードであるDom\EntityのcloneNodeメソッドの挙動を示しています。Dom\Entityオブジェクトは子ノードを持たないため、cloneNodeメソッドの$deep引数をtrue（深くクローン）にしてもfalse（浅くクローン）にしても、結果としてコピーされる内容に違いは現れません。これは一般的なXML要素など、子ノードを持つDom\Nodeのクローンとは異なる点ですので注意が必要です。cloneNodeは常に新しいオブジェクトを生成します。また、メソッドが失敗した場合はfalseが返される可能性があるため、実運用では戻り値の確認をお勧めします。

PHP Dom\Entity::cloneNodeでノードを複製する


1<?php
2
3/**
4 * Dom\Entity::cloneNode() メソッドの使用例を示します。
5 *
6 * Dom\Entity は、XML や HTML の DTD (Document Type Definition) で定義されるエンティティを表すノードです。
7 * 例えば、&amp; や &nbsp; のような記号、あるいはカスタム定義された &copyright; のようなエンティティが該当します。
8 *
9 * cloneNode メソッドは、指定された Dom\Entity ノードの複製を作成します。
10 *
11 * 注意点として、Dom\Entity ノードは通常子ノードを持たないため、
12 * cloneNode メソッドの $deep 引数 (true で子ノードも複製、false でノード自身のみ複製) の効果は、
13 * Dom\Element のような他のノードを複製する場合ほど顕著ではありません。
14 * どちらの場合も、エンティティ自身の情報が複製された新しい Dom\Entity オブジェクトが生成されます。
15 */
16function demonstrateDomEntityCloneNode(): void
17{
18    // 1. Dom\Document を作成し、DTD とカスタムエンティティを定義したXMLをロードします。
19    //    これにより、Dom\DocumentType から Dom\Entity インスタンスが取得可能になります。
20    $xmlString = <<<XML
21<!DOCTYPE root [
22  <!ENTITY customCopyright "© MyCompany Inc.">
23  <!ENTITY customVersion "1.0">
24]>
25<root>
26    <p>この文書は &customCopyright; によって保護されています。</p>
27    <p>バージョン: &customVersion;</p>
28</root>
29XML;
30
31    $dom = new Dom\Document();
32    // XMLをロードし、DTDに含まれるエンティティがパースされるようにします。
33    $dom->loadXML($xmlString);
34
35    $originalEntity = null;
36
37    // 2. Dom\DocumentType から entities コレクションを通じて Dom\Entity インスタンスを取得します。
38    //    ここでは "customCopyright" という名前のエンティティを探します。
39    if ($dom->doctype && $dom->doctype->entities) {
40        foreach ($dom->doctype->entities as $entity) {
41            // 見つかったノードが Dom\Entity のインスタンスであり、期待する名前であることを確認します。
42            if ($entity instanceof Dom\Entity && $entity->nodeName === 'customCopyright') {
43                $originalEntity = $entity;
44                break;
45            }
46        }
47    }
48
49    if (!$originalEntity) {
50        echo "エラー: 'customCopyright' エンティティノードが見つかりませんでした。" . PHP_EOL;
51        return;
52    }
53
54    echo "--- 元の Dom\\Entity ノードの情報 ---" . PHP_EOL;
55    echo "  ノード名: " . $originalEntity->nodeName . PHP_EOL;
56    echo "  ノード値 (エンティティの置換テキスト): " . $originalEntity->nodeValue . PHP_EOL;
57    echo "  元のオブジェクトID: " . spl_object_id($originalEntity) . PHP_EOL;
58    echo PHP_EOL;
59
60    // 3. cloneNode(false) を使用してシャロークローン (浅い複製) を作成します。
61    //    引数 $deep を false に設定すると、ノード自身のみが複製され、子ノードは複製されません。
62    //    Dom\Entity は通常子ノードを持たないため、この場合もエンティティ自身の情報が複製されます。
63    $shallowClone = $originalEntity->cloneNode(false);
64
65    if ($shallowClone === false) {
66        echo "エラー: シャロークローンに失敗しました。" . PHP_EOL;
67        return;
68    }
69
70    echo "--- シャロークローンされた Dom\\Entity ノードの情報 (cloneNode(false)) ---" . PHP_EOL;
71    echo "  ノード名: " . $shallowClone->nodeName . PHP_EOL;
72    echo "  ノード値 (エンティティの置換テキスト): " . $shallowClone->nodeValue . PHP_EOL;
73    echo "  クローンされたオブジェクトID: " . spl_object_id($shallowClone) . PHP_EOL;
74    // 元のノードとクローンされたノードは別々のオブジェクトであることを確認します。
75    echo "  元のノードと異なるオブジェクトか: " . (spl_object_id($originalEntity) !== spl_object_id($shallowClone) ? 'はい' : 'いいえ') . PHP_EOL;
76    echo PHP_EOL;
77
78    // 4. cloneNode(true) を使用してディープクローン (深い複製) を作成します。
79    //    引数 $deep を true に設定すると、ノード自身とそのすべての子ノードが複製されます。
80    //    しかし、Dom\Entity は通常子ノードを持たないため、この場合もシャロークローンと実質的に同じ結果になります。
81    $deepClone = $originalEntity->cloneNode(true);
82
83    if ($deepClone === false) {
84        echo "エラー: ディープクローンに失敗しました。" . PHP_EOL;
85        return;
86    }
87
88    echo "--- ディープクローンされた Dom\\Entity ノードの情報 (cloneNode(true)) ---" . PHP_EOL;
89    echo "  ノード名: " . $deepClone->nodeName . PHP_EOL;
90    echo "  ノード値 (エンティティの置換テキスト): " . $deepClone->nodeValue . PHP_EOL;
91    echo "  クローンされたオブジェクトID: " . spl_object_id($deepClone) . PHP_EOL;
92    // 元のノードとクローンされたノードは別々のオブジェクトであることを確認します。
93    echo "  元のノードと異なるオブジェクトか: " . (spl_object_id($originalEntity) !== spl_object_id($deepClone) ? 'はい' : 'いいえ') . PHP_EOL;
94    echo PHP_EOL;
95
96    echo "--- まとめ ---" . PHP_EOL;
97    echo "Dom\\Entity は通常子ノードを持たないため、" . PHP_EOL;
98    echo "cloneNode(false) (シャロークローン) と cloneNode(true) (ディープクローン) の結果に" . PHP_EOL;
99    echo "実質的な差はほとんどありません。" . PHP_EOL;
100    echo "どちらの場合も、元のノードとは異なる新しい Dom\\Entity オブジェクトが生成されます。" . PHP_EOL;
101}
102
103// サンプル関数を実行します。
104demonstrateDomEntityCloneNode();

PHPのDom\Entity::cloneNode()メソッドは、XMLやHTMLのDTD（Document Type Definition）で定義されたエンティティノードを複製するために使用されます。エンティティノードとは、&のような特殊文字の参照や、カスタム定義された&customCopyright;のような、特定のテキストを表す記号のことです。

このメソッドは引数bool $deepを受け取ります。この引数をfalse（デフォルト）に設定すると、ノード自身のみが複製されるシャロークローンを作成します。trueに設定すると、ノード自身とそのすべての子ノードを含むディープクローンを作成します。しかし、Dom\Entityノードは通常子ノードを持たないため、$deep引数の値に関わらず、エンティティ自身の情報が複製された新しいDom\Entityオブジェクトが生成されます。

メソッドは複製に成功した場合、新しいDom\Nodeオブジェクト（実際にはDom\Entityのインスタンス）を返します。複製が失敗した場合はfalseを返します。サンプルコードでは、元のエンティティノードとは完全に独立した新しいDom\Entityオブジェクトが作成され、$deep引数をfalseとtrueのどちらにしても、実質的に同じ複製結果が得られることが示されています。

Dom\Entity::cloneNode() メソッドは、DTDで定義されるエンティティの複製に使われます。Dom\Entity は通常子ノードを持たないため、引数 $deep（子ノードも複製するかどうか）を true にしても false にしても、複製される内容に実質的な違いはありません。どちらの場合も元のエンティティとは独立した新しい Dom\Entity オブジェクトが生成されます。複製が失敗した場合は false を返すため、必ず戻り値を確認してエラー処理を行うようにしてください。この振る舞いは、子ノードを持つ Dom\Element などの他のノードを複製する場合と異なるため、混同しないよう注意が必要です。