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

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

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

基本的な使い方

appendChildメソッドは、指定したノードをエンティティ参照ノードの子リストの末尾に追加しようと試みるメソッドです。しかし、Dom\EntityReferenceクラスが表すエンティティ参照ノードは、DOMの仕様上、子ノードを持つことができません。これは、エンティティ参照が単一のまとまりとして扱われる読み取り専用のノードであり、その内部構造を変更することが許可されていないためです。この特性により、Dom\EntityReferenceオブジェクトに対してappendChildメソッドを呼び出すと、操作は必ず失敗し、常にDOMExceptionという例外がスローされます。引数としてどのような種類のノードを渡した場合でも、この動作は変わりません。したがって、このメソッドはDom\EntityReferenceオブジェクトに対しては実質的に使用することができず、プログラム上で呼び出すとエラーを引き起こします。DOMツリーを操作する際には、このようにノードの種類によって実行できる操作が異なることを理解しておくことが重要です。

構文(syntax)


1<?php
2$domDocument = new \Dom\Document();
3
4$entityReferenceNode = $domDocument->createEntityReference('example_entity');
5$newChildNode = $domDocument->createElement('new_element');
6
7$entityReferenceNode->appendChild($newChildNode);

引数(parameters)

Dom\Node $node

Dom\Node $node: 追加する子ノードを指定します。

戻り値(return)

Dom\Node|false

指定された要素 (Dom\Node) を現在のノードの子要素として追加します。成功した場合は追加された子ノード (Dom\Node)、失敗した場合は false を返します。

サンプルコード

PHP DOM appendChild でHTMLを構築する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMNode::appendChild を使用してHTMLドキュメントを動的に構築するサンプル関数
7 *
8 * この関数は、親ノードに新しい子ノードを追加する appendChild メソッドの
9 * 最も一般的で基本的な使い方を示します。
10 *
11 * @return string 生成されたHTML文字列
12 */
13function createHtmlUsingAppendChild(): string
14{
15    // 1. DOMDocumentオブジェクトを作成します。これがHTMLドキュメントの基盤となります。
16    $dom = new DOMDocument('1.0', 'UTF-8');
17
18    // 出力されるHTMLを読みやすくするためにフォーマットします。
19    $dom->formatOutput = true;
20
21    // 2. HTMLの各要素を createElement で作成します。
22    $htmlElement = $dom->createElement('html');
23    $bodyElement = $dom->createElement('body');
24    $pElement = $dom->createElement('p');
25
26    // 3. 要素内に表示するテキストを createTextNode で作成します。
27    $textNode = $dom->createTextNode('Hello, World!');
28
29    // 4. appendChild メソッドを使い、ノードを親子関係になるように追加していきます。
30    // <p> タグにテキストノードを追加します。
31    // 結果: <p>Hello, World!</p>
32    $pElement->appendChild($textNode);
33
34    // <body> タグに <p> 要素を追加します。
35    $bodyElement->appendChild($pElement);
36
37    // <html> タグに <body> 要素を追加します。
38    $htmlElement->appendChild($bodyElement);
39
40    // 最後に、ドキュメントのルートに <html> 要素を追加します。
41    $dom->appendChild($htmlElement);
42
43    // 5. 作成したDOMオブジェクトをHTML文字列として返します。
44    return $dom->saveHTML();
45}
46
47// 関数を実行し、生成されたHTMLを出力します。
48echo createHtmlUsingAppendChild();
49
50?>

appendChildメソッドは、あるノードの子ノードリストの末尾に、新しい子ノードを追加するための機能です。HTMLやXMLの文書構造をプログラム上で動的に組み立てる際に使用される、基本的なメソッドです。

サンプルコードでは、createElementやcreateTextNodeで作成した<html>、<body>、<p>要素やテキストといった個別のノードを、appendChildを使って親子関係になるように連結しています。具体的には、まずテキストノードを<p>要素に追加し、次にその<p>要素を<body>要素へ、さらに<body>要素を<html>要素へと、内側から外側に向かって階層的に追加していくことで、最終的なHTMLドキュメントを構築しています。

このメソッドの引数には、追加したい子ノードとなるDom\Nodeオブジェクトを渡します。処理が成功すると、戻り値として追加されたノード自身が返されます。もしノードの追加に失敗した場合はfalseが返ります。このようにappendChildは、DOMを操作して文書を構築する上で中心的な役割を果たします。

appendChildメソッドは、親ノードの子ノードリストの末尾に新しいノードを追加します。注意点として、追加するノードは、必ず同じDOMDocumentオブジェクト内で作成されたものである必要があります。異なるドキュメントのノードを追加しようとするとエラーになります。また、追加するノードが既にドキュメント内の別の場所に存在する場合、そのノードは元の場所からコピーされるのではなく「移動」されます。この挙動は意図しない要素の消失に繋がる可能性があるため、正しく理解しておくことが重要です。処理に失敗するとfalseを返すため、確実な処理が求められる場面では戻り値の確認を推奨します。DOMDocumentの生成時に文字コードを指定することも文字化けを防ぐために不可欠です。

SimpleXMLにDOMで要素を追加する


1<?php
2
3/**
4 * SimpleXMLで読み込んだXMLに、DOMの機能を使って新しい子要素を追加するサンプルです。
5 * SimpleXMLオブジェクトをDOMオブジェクトに変換することで、appendChildメソッドを利用できます。
6 */
7function append_child_to_simplexml_element(): void
8{
9    // 1. 操作対象のXML文字列を定義します。
10    $xmlString = <<<XML
11    <?xml version="1.0" encoding="UTF-8"?>
12    <bookshelf>
13        <book>
14            <title>Learning PHP</title>
15            <author>John Doe</author>
16        </book>
17    </bookshelf>
18    XML;
19
20    // 2. SimpleXMLオブジェクトとしてXMLを読み込みます。
21    $sxe = simplexml_load_string($xmlString);
22    if ($sxe === false) {
23        echo 'Error: Cannot create SimpleXMLElement object.' . PHP_EOL;
24        return;
25    }
26
27    // 3. SimpleXMLオブジェクトをDOMElementオブジェクトに変換します。
28    //    appendChildメソッドはDOMの機能なので、この変換が必要です。
29    $domElement = dom_import_simplexml($sxe);
30    if ($domElement === false) {
31        echo 'Error: Cannot convert SimpleXMLElement to DOMElement.' . PHP_EOL;
32        return;
33    }
34
35    // 4. 新しい要素を作成するために、オーナーであるDOMDocumentオブジェクトを取得します。
36    $domDocument = $domElement->ownerDocument;
37
38    // 5. 新しく追加する <book> 要素とその子要素を作成します。
39    $newBook = $domDocument->createElement('book');
40    $newTitle = $domDocument->createElement('title', 'Advanced PHP');
41    $newAuthor = $domDocument->createElement('author', 'Jane Smith');
42
43    // 6. 新しい <book> 要素に <title> と <author> を子要素として追加します。
44    $newBook->appendChild($newTitle);
45    $newBook->appendChild($newAuthor);
46
47    // 7. メインの要素 (<bookshelf>) に、作成した新しい <book> 要素を子として追加します。
48    $domElement->appendChild($newBook);
49
50    // 8. 変更後のDOMDocumentを整形してXML文字列として出力します。
51    $domDocument->formatOutput = true;
52    echo $domDocument->saveXML();
53}
54
55// 関数を実行して結果を表示します。
56append_child_to_simplexml_element();
57
58?>

このサンプルコードは、PHPのSimpleXML機能で読み込んだXMLデータに対して、DOMの機能を利用して新しい子要素を追加する方法を示しています。appendChildメソッドがその中心的な役割を担います。

appendChildメソッドは、ある要素（親ノード）の持つ子要素リストの末尾に、新しい要素（子ノード）を追加するためのものです。引数には追加したいDom\Nodeオブジェクトを指定します。処理が成功すると、追加されたノードオブジェクト自身を返り値として受け取ることができ、失敗した場合はfalseを返します。

コードの流れとしては、まずsimplexml_load_string()でXMLを読み込みますが、appendChildはDOMのメソッドであるため、dom_import_simplexml()を使ってSimpleXMLオブジェクトをDOMオブジェクトに変換する必要があります。次に、createElement()で追加したい新しい<book>要素とその内容（<title>や<author>）を作成します。そして、作成した新しい<book>要素を、元のXMLのルート要素である<bookshelf>に対してappendChildメソッドで追加しています。最後にsaveXML()で変更後のXML全体を出力すると、新しい書籍情報が追加されたことが確認できます。

appendChildはDOM拡張のメソッドであり、SimpleXMLオブジェクトでは直接利用できません。そのため、サンプルコードのようにdom_import_simplexml関数を使って、まずSimpleXMLオブジェクトをDOMオブジェクトへ変換する手順が必須です。新しい要素を作成する際には、new DOMElement()のように直接インスタンスを生成するのではなく、必ず元のXML文書を表すownerDocumentオブジェクトのcreateElementメソッドを使用してください。これにより、追加する要素が正しく文書に紐付けられます。この変換と正しい要素作成の手順を守ることで、SimpleXMLで読み込んだXMLデータに対して、DOMの豊富な機能を使った柔軟な操作が可能になります。