前言
PHP 提供兩大 XML 處理體系:DOM (Document Object Model) 樹狀記憶體模型,適合中小檔案隨機存取與修改;XMLReader/Writer 流式拉取/推送模型,適合大檔案、低記憶體場景。本文彙整核心類別的所有公共方法、屬性與常數,供開發速查。
一、DOMDocument 類別
載入與儲存
| 方法 | 簽名 | 說明 |
load | load(string $filename, int $options = 0): bool | 從檔案載入 XML,支援 LIBXML_NOENT 等選項 |
loadXML | loadXML(string $source, int $options = 0): bool | 從字串載入 XML |
loadHTML | loadHTML(string $source, int $options = 0): bool | 載入 HTML (容錯模式) |
loadHTMLFile | loadHTMLFile(string $filename, int $options = 0): bool | 從檔案載入 HTML |
save | save(string $filename, int $options = 0): int|false | 存檔,返回位元組數 |
saveXML | saveXML(?DOMNode $node = null, int $options = 0): string|false | 輸出 XML 字串,可指定節點片段 |
saveHTML | saveHTML(?DOMNode $node = null): string|false | 輸出 HTML 字串 |
validate | validate(): bool | 依據 DTD/Schema 驗證 |
schemaValidate | schemaValidate(string $filename, int $flags = 0): bool | 依據 XSD 驗證 |
schemaValidateSource | schemaValidateSource(string $source, int $flags = 0): bool | 從字串 XSD 驗證 |
節點建立
| 方法 | 簽名 | 說明 |
createElement | createElement(string $name, string $value = ""): DOMElement|false | 建立元素節點,可帶文字內容 |
createElementNS | createElementNS(string $namespace, string $qualifiedName, string $value = ""): DOMElement|false | 帶命名空間建立元素 |
createTextNode | createTextNode(string $content): DOMText|false | 建立文字節點 (自動轉義) |
createCDATASection | createCDATASection(string $data): DOMCdataSection|false | 建立 CDATA 區段 |
createComment | createComment(string $data): DOMComment|false | 建立註解節點 |
createAttribute | createAttribute(string $name): DOMAttr|false | 建立屬性節點 |
createAttributeNS | createAttributeNS(string $namespace, string $qualifiedName): DOMAttr|false | 帶命名空間建立屬性 |
createDocumentFragment | createDocumentFragment(): DOMDocumentFragment | 建立文檔片段 (批次插入高效) |
createProcessingInstruction | createProcessingInstruction(string $target, string $data): DOMProcessingInstruction|false | 建立處理指令 |
查詢與遍歷
| 方法 | 簽名 | 說明 |
getElementsByTagName | getElementsByTagName(string $name): DOMNodeList | 依標籤名獲取節點列表 (即時動態) |
getElementsByTagNameNS | getElementsByTagNameNS(string $namespace, string $localName): DOMNodeList | 命名空間版 |
getElementById | getElementById(string $id): DOMElement|false | 依 ID 獲取 (需 DTD/Schema 定義 ID 型別) |
getElementsByClassName | getElementsByClassName(string $class): DOMNodeList | 依 class 獲取 (HTML 文檔) |
屬性與配置
formatOutput (bool):輸出時縮排格式化
preserveWhiteSpace (bool, default true):保留空白文字節點
resolveExternals (bool):載入外部實體
substituteEntities (bool):替換實體引用
strictErrorChecking (bool, default true):嚴格錯誤檢查
recover (bool):修復模式載入不完整 XML/HTML
documentElement (DOMElement):根元素節點
doctype (DOMDocumentType):DOCTYPE 節點
implementation (DOMImplementation):實作物件
encoding (string):XML 編碼
version (string):XML 版本
standalone (bool):獨立聲明
documentURI (string):文檔 URI
config (DOMConfiguration):配置物件 (PHP 5.3+)
二、DOMElement 類別 (元素節點)
| 方法/屬性 | 簽名/類型 | 說明 |
tagName | string (readonly) | 標籤名 (大寫) |
getAttribute | getAttribute(string $name): string | 獲取屬性值 (不存在回傳空字串) |
getAttributeNS | getAttributeNS(string $ns, string $name): string | 命名空間版 |
setAttribute | setAttribute(string $name, string $value): bool | 設定屬性 |
setAttributeNS | setAttributeNS(string $ns, string $name, string $value): bool | 命名空間版 |
removeAttribute | removeAttribute(string $name): bool | 移除屬性 |
removeAttributeNS | removeAttributeNS(string $ns, string $name): bool | 命名空間版 |
hasAttribute | hasAttribute(string $name): bool | 檢查屬性存在 |
hasAttributeNS | hasAttributeNS(string $ns, string $name): bool | 命名空間版 |
getAttributeNode | getAttributeNode(string $name): DOMAttr|false | 獲取屬性節點物件 |
setAttributeNode | setAttributeNode(DOMAttr $attr): DOMAttr|false | 設定屬性節點 |
removeAttributeNode | removeAttributeNode(DOMAttr $attr): DOMAttr|false | 移除屬性節點 |
getElementsByTagName | getElementsByTagName(string $name): DOMNodeList | 後代元素查詢 |
getElementsByTagNameNS | getElementsByTagNameNS(string $ns, string $local): DOMNodeList | 命名空間版 |
setIdAttribute | setIdAttribute(string $name, bool $isId): void | 宣告屬性為 ID 型別 (供 getElementById 用) |
三、DOMNode 類別 (所有節點基類)
核心屬性
| 屬性 | 類型 | 說明 |
nodeType | int | 節點類型常數 (XML_ELEMENT_NODE=1, XML_TEXT_NODE=3, XML_CDATA_SECTION_NODE=4, ...) |
nodeName | string | 節點名稱 (元素為 tagName,屬性為名稱,文字為 #text,文檔為 #document) |
nodeValue | string|null | 節點值 (文字/註解/CDATA 內容,元素為 null) |
textContent | string | 該節點及所有後代文字內容串聯 (讀寫皆可) |
parentNode | DOMNode|null | 父節點 |
childNodes | DOMNodeList | 子節點列表 (含文字、註解) |
firstChild | DOMNode|null | 第一個子節點 |
lastChild | DOMNode|null | 最後一個子節點 |
previousSibling | DOMNode|null | 前一個同級節點 |
nextSibling | DOMNode|null | 下一個同級節點 |
ownerDocument | DOMDocument | 所屬文檔 |
namespaceURI | string|null | 命名空間 URI |
prefix | string|null | 命名空間前綴 |
localName | string | 本地名稱 (不含前綴) |
baseURI | string | 基礎 URI (XML Base) |
核心操作方法
| 方法 | 簽名 | 說明 |
appendChild | appendChild(DOMNode $node): DOMNode|false | 附加子節點 (自動從原位置移動) |
insertBefore | insertBefore(DOMNode $new, ?DOMNode $ref = null): DOMNode|false | 在參考節點前插入,$ref 為 null 等同 appendChild |
replaceChild | replaceChild(DOMNode $new, DOMNode $old): DOMNode|false | 替換子節點 |
removeChild | removeChild(DOMNode $old): DOMNode|false | 移除子節點 |
cloneNode | cloneNode(bool $deep = false): DOMNode | 複製節點,$deep=true 遞歸複製後代 |
hasChildNodes | hasChildNodes(): bool | 是否有子節點 |
hasAttributes | hasAttributes(): bool | 是否有屬性 (僅元素節點有效) |
normalize | normalize(): void | 合併相鄰文字節點、移除空文字節點 |
isSupported | isSupported(string $feature, string $version): bool | 檢查 DOM 功能支援 |
isSameNode | isSameNode(DOMNode $other): bool | 是否同一節點物件 |
isEqualNode | isEqualNode(DOMNode $other): bool | 結構值相等比較 |
lookupNamespaceURI | lookupNamespaceURI(string $prefix): string|false | 查詢前綴對應命名空間 |
lookupPrefix | lookupPrefix(string $ns): string|false | 查詢命名空間對應前綴 |
isDefaultNamespace | isDefaultNamespace(string $ns): bool | 檢查是否為預設命名空間 |
compareDocumentPosition | compareDocumentPosition(DOMNode $other): int | 節點文檔位置關係位元組 |
getRootNode | getRootNode(array $options = []): DOMNode | 獲取根節點 (PHP 8.0+) |
四、XMLReader (Pull Parser)
常數:節點類型
XMLReader::NONE = 0;
XMLReader::ELEMENT = 1; // 開始標籤
XMLReader::ATTRIBUTE = 2; // 屬性
XMLReader::TEXT = 3; // 文字內容
XMLReader::CDATA = 4; // CDATA
XMLReader::ENTITY_REF = 5; // 實體引用
XMLReader::ENTITY = 6; // 實體宣告
XMLReader::PI = 7; // 處理指令
XMLReader::COMMENT = 8; // 註解
XMLReader::DOC = 9; // 文檔節點
XMLReader::DOC_TYPE = 10; // DOCTYPE
XMLReader::DOC_FRAGMENT = 11; // 文檔片段
XMLReader::NOTATION = 12; // 符號宣告
XMLReader::WHITESPACE = 13; // 空白文字
XMLReader::SIGNIFICANT_WHITESPACE = 14; // 重要空白
XMLReader::END_ELEMENT = 15; // 結束標籤
XMLReader::END_ENTITY = 16; // 實體結束
XMLReader::XML_DECLARATION = 17; // XML 宣告
核心方法
| 方法 | 簽名 | 說明 |
open | open(string $uri, string $encoding = '', int $options = 0): bool | 開啟 URI (檔案/HTTP/流) |
xml | xml(string $source, string $encoding = '', int $options = 0): bool | 載入字串 |
read | read(): bool | 移至下一個節點,結束回傳 false |
next | next(string $localName = ''): bool | 跳至下一個同名元素 (跳過子樹) |
close | close(): bool | 關閉輸入 |
getAttribute | getAttribute(string $name): string|false | 當前元素屬性值 |
getAttributeNs | getAttributeNs(string $name, string $ns): string|false | 命名空間版 |
getAttributeNo | getAttributeNo(int $index): string|false | 依索引取屬性 |
moveToAttribute | moveToAttribute(string $name): bool | 游標移至指定屬性 |
moveToAttributeNo | moveToAttributeNo(int $index): bool | 游標移至索引屬性 |
moveToFirstAttribute | moveToFirstAttribute(): bool | 游標移至第一個屬性 |
moveToNextAttribute | moveToNextAttribute(): bool | 游標移至下一個屬性 |
moveToElement | moveToElement(): bool | 游標回到擁有屬性的元素 |
readString | readString(): string | 讀取當前文字/CDATA 節點內容 |
readInnerXml | readInnerXml(): string|false | 讀取當前元素內部 XML |
readOuterXml | readOuterXml(): string|false | 讀取當前元素完整 XML (含標籤) |
expand | expand(?DOMDocument $base = null): DOMNode|false | 將當前節點展開為 DOM 子樹 (可選基礎文檔) |
setSchema | setSchema(string $filename): bool | 設定 XSD 驗證 |
setRelaxNGSchema | setRelaxNGSchema(string $filename): bool | 設定 RelaxNG 驗證 |
isValid | isValid(): bool | 當前節點是否通過驗證 |
lookupNamespace | lookupNamespace(string $prefix): string|false | 查詢命名空間 |
getParserProperty | getParserProperty(int $property): bool | 獲取解析器屬性 |
setParserProperty | setParserProperty(int $property, bool $value): bool | 設定解析器屬性 |
解析器屬性常數
XMLReader::VALIDATE (1):驗證模式
XMLReader::SUBST_ENTITIES (2):替換實體
XMLReader::LOADDTD (4):載入外部 DTD
五、XMLWriter (流式產生)
對應 XMLReader 的寫入端,記憶體效率極高:
$writer = new XMLWriter();
$writer->openUri('output.xml');
$writer->setIndent(true);
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('root');
$writer->writeElement('item', '值1');
$writer->writeAttribute('attr', '值2');
$writer->endElement();
$writer->endDocument();
$writer->flush();
六、選型建議
- 配置檔、小型資料交換、需修改結構 →
DOMDocument + XPath
- 超大檔 (>100MB)、單向讀取、記憶體受限 →
XMLReader
- 大量資料匯出 XML →
XMLWriter
- 簡單陣列轉 XML →
SimpleXML (內部基於 libxml)
- HTML 解析/清洗 →
DOMDocument::loadHTML + DOMXPath 或 Masterminds/HTML5-Parser
結語
PHP 的 XML 生態建構在 libxml2 之上,功能完整且符合 W3C 標準。熟練掌握 DOM 隨機存取 與 Reader/Writer 流式處理 兩大範式,並善用 XPath 查詢、Schema 驗證、XSLT 轉換,即能應對企業級 XML 整合、報表產出、異構系統對接等各類場景。