萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 向 XML 新增節點:DOMDocument 完整操作指南與命名空間處理

在電子發票、API 回應、設定檔產生等場景,常需**動態建立或修改 XML**。PHP 的 DOMDocument 提供標準、完整的節點操作 API,支援元素、屬性、CDATA、命名空間、文檔類型宣告等。本文從建立文檔、新增節點、屬性、CDATA、命名空間到輸出格式化,提供生產級範例。

核心概念:節點類型與建立方法

節點類型建立方法說明
Element$dom->createElement('tag', 'content')一般元素,內容會自動實體編碼
Attribute$elem->setAttribute('name', 'value')或 $dom->createAttribute('name')
Text$dom->createTextNode('text')純文字,不解析標籤
CDATASection$dom->createCDATASection('data')包含特殊字元、不轉義
Comment$dom->createComment('note')註解節點
ProcessingInstruction$dom->createProcessingInstruction('target', 'data')如 ``
DocumentType$dom->createDocumentType('root', 'publicId', 'systemId')DTD 宣告

完整範例:建立電子發票 XML(含命名空間)

<?php
/**
 * 產生符合台灣電子發票規格的 XML 範例
 */
function generateInvoiceXml(array $data): string
{
    $dom = new DOMDocument('1.0', 'UTF-8');
    $dom->formatOutput = true;
    $dom->preserveWhiteSpace = false;

    // 註冊命名空間
    $ns = 'urn:GEINV:eInvoiceMessage:C0401:3.1';
    $root = $dom->createElementNS($ns, 'Invoice');
    $root->setAttribute('xmlns', $ns);
    $root->setAttribute('xmlns:xsi', 'https://www.w3.org/2001/XMLSchema-instance');
    $dom->appendChild($root);

    // Main 區塊
    $main = $dom->createElement('Main');
    $root->appendChild($main);

    // 發票基本資訊
    $fields = [
        'InvoiceNumber' => $data['number'] ?? '',
        'InvoiceDate' => $data['date'] ?? date('Y/m/d'),
        'SellerId' => $data['seller_ban'] ?? '',
        'BuyerId' => $data['buyer_ban'] ?? '',
        'TotalAmount' => $data['total'] ?? 0,
    ];
    foreach ($fields as $tag => $value) {
        $elem = $dom->createElement($tag, (string)$value);
        $main->appendChild($elem);
    }

    // Details 明細(多筆)
    $details = $dom->createElement('Details');
    $main->appendChild($details);

    foreach ($data['items'] ?? [] as $item) {
        $prod = $dom->createElement('ProductItem');
        $details->appendChild($prod);

        $prod->appendChild($dom->createElement('Description', $item['name']));
        $prod->appendChild($dom->createElement('Quantity', (string)$item['qty']));
        $prod->appendChild($dom->createElement('UnitPrice', (string)$item['price']));
        $prod->appendChild($dom->createElement('Amount', (string)($item['qty'] * $item['price'])));

        // 稅別:CDATA 避免特殊字元
        $tax = $dom->createElement('TaxType');
        $tax->appendChild($dom->createCDATASection($item['tax_type'] ?? '1'));
        $prod->appendChild($tax);
    }

    // 簽章區塊(預留)
    $signature = $dom->createElement('Signature');
    $root->appendChild($signature);

    return $dom->saveXML();
}

// 使用
$invoiceData = [
    'number' => 'AB12345678',
    'date' => '2024/01/15',
    'seller_ban' => '12345678',
    'buyer_ban' => '87654321',
    'total' => 1150,
    'items' => [
        ['name' => '商品A', 'qty' => 1, 'price' => 1000, 'tax_type' => '1'],
        ['name' => '商品B & 特殊字元 <>&', 'qty' => 1, 'price' => 150, 'tax_type' => '1'],
    ],
];

header('Content-Type: application/xml; charset=utf-8');
echo generateInvoiceXml($invoiceData);
?>

進階技巧

1. 插入節點到指定位置

<?php
// 在 $referenceNode 之前插入
$parent->insertBefore($newNode, $referenceNode);

// 在 $referenceNode 之後插入
$parent->insertBefore($newNode, $referenceNode->nextSibling);

// 追加到最後
$parent->appendChild($newNode);
?>

2. 複製/移動節點(跨文檔需 importNode)

<?php
$sourceDom = new DOMDocument();
$sourceDom->loadXML('A');
$sourceItem = $sourceDom->getElementsByTagName('item')->item(0);

$targetDom = new DOMDocument();
$targetDom->loadXML('');

// 跨文檔必須 importNode(deep=true 含子樹)
$imported = $targetDom->importNode($sourceItem, true);
$targetDom->documentElement->appendChild($imported);

echo $targetDom->saveXML();
// A
?>

3. 移除命名空間前綴(輸出簡潔 XML)

<?php
function stripNamespaces(DOMDocument $dom): void
{
    $xpath = new DOMXPath($dom);
    // 移除所有元素的 namespaceURI
    foreach ($xpath->query('//*') as $node) {
        $node->removeAttribute('xmlns');
        // 注意:prefix 無法直接移除,需重建元素或接受輸出含前綴
    }
}
?>

4. 格式化輸出控制

<?php
$dom->formatOutput = true;       // 縮排
$dom->preserveWhiteSpace = false; // 忽略原文空白

// 自訂縮排(PHP 8.0+)
$dom->formatOutput = true;
// 無內建自訂縮排字元,需後處理:
$xml = $dom->saveXML();
$xml = preg_replace('/^(\\s*)/m', str_repeat('  ', 2), $xml); // 簡易調整
?>

常見錯誤與解決

  1. 命名空間不匹配:`createElementNS()` 必須配合正確 URI,XPath 查詢需 `registerNamespace()`。
  2. 特殊字元雙重編碼:`createElement('tag', '<test>')` 會輸出 `&lt;test&gt;`,若需原樣輸出用 `createTextNode()` 或 `createCDATASection()`。
  3. 文檔片段:一次建立多個同層節點用 `DocumentFragment` 避免重複掛載。
  4. 記憶體洩漏:大量建立節點後,`$dom = null; gc_collect_cycles();` 釋放。

替代方案:XMLWriter(串流寫入、超大檔、低記憶體)

<?php
$writer = new XMLWriter();
$writer->openMemory();
$writer->setIndent(true);
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('contacts');

for ($i = 1; $i <= 100000; $i++) {
    $writer->startElement('contact');
    $writer->writeAttribute('id', (string)$i);
    $writer->writeElement('name', "User $i");
    $writer->endElement(); // contact
}

$writer->endElement(); // contacts
$writer->endDocument();

echo $writer->outputMemory(); // 或 $writer->openUri('file.xml') 直接寫檔
?>

DOMDocument 適合**需隨機存取、修改、XPath 查詢**的中小型 XML;XMLWriter 適合**單向產生超大 XML**。掌握兩者,XML 產出無懼任何場景。

copyright © 萬盛學電腦網 all rights reserved