PHP DOM 扩展解析命名空间 XML 的节点选择

我第一次遇到“PHP DOM 扩展明明加载成功，XPath 却查不到节点”时，XML 本身并没有坏，真正漏掉的是命名空间。只要 XML 元素属于某个 namespaceURI，XPath 查询就需要在查询对象上注册一个前缀，并在表达式里显式写出来。这个前缀可以和 XML 原文不同，但它必须映射到同一个 URI。

这篇只围绕一个小问题展开：用 DOMDocument 加载带命名空间的 XML 后，怎样稳定选择目标节点。完整做法是读取根元素的 namespaceURI，通过 DOMXPath::registerNamespace() 绑定查询前缀，再调用 DOMXPath::query() 获取 DOMNodeList。

先看清 XML 元素属于哪个命名空间

下面的 XML 使用默认命名空间，元素名称看起来是 catalog 和 item，但它们实际都属于 urn:demo:catalog。默认命名空间不会自动变成 XPath 中的“无前缀匹配”，这是最容易踩坑的地方。

DOMXPath

解析后，可以从 documentElement 读取命名空间 URI。这里关注的是 URI，不是 XML 里有没有写一个可见前缀。

DOMXPath
XML;

$dom = new DOMDocument();
// 关闭空白节点保留，后面遍历结果时更容易只关注元素节点。
$dom->preserveWhiteSpace = false;

if (!$dom->loadXML($xml)) {
    // 输入不符合 XML 语法时立即停止，避免用不完整文档继续查询。
    throw new RuntimeException('XML 文档加载失败');
}

$root = $dom->documentElement;
if ($root === null || $root->namespaceURI === null) {
    // 没有根元素或命名空间时，不能假设 XPath 前缀应该绑定到什么 URI。
    throw new RuntimeException('XML 根元素缺少命名空间');
}

$namespaceUri = $root->namespaceURI;
echo $root->nodeName . PHP_EOL;
echo $namespaceUri . PHP_EOL;

实战中我会先打印或记录这两个值：根节点名称帮助确认加载的是预期文档，namespaceURI 则决定后面 registerNamespace() 的第二个参数。不要根据标签名称猜 URI，也不要把默认命名空间当成空字符串。

把 namespaceURI 注册为 XPath 查询前缀

DOMXPath 需要绑定一个查询侧前缀。这个前缀只是 XPath 表达式里的别名，不要求和 XML 原文的前缀一致；对于默认命名空间，通常人为取一个短前缀，例如 ns。

registerNamespace('ns', $namespaceUri);

// 每一级元素都写上查询前缀，避免默认命名空间导致空结果。
$nodes = $xpath->query('//ns:catalog/ns:item');
if ($nodes === false) {
    // XPath 表达式非法时不要把 false 当成空的节点列表。
    throw new RuntimeException('XPath 表达式无效');
}

foreach ($nodes as $node) {
    if (!$node instanceof DOMElement) {
        // 只处理元素节点，避免把其他节点类型强行当成属性容器。
        continue;
    }

    echo $node->getAttribute('code') . ': ' . trim($node->textContent) . PHP_EOL;
}

这里有两个细节值得保留。第一，catalog 和 item 都属于同一个命名空间，所以 XPath 的两级名称都写成 ns: 前缀。第二，查询失败和查询结果为空不是同一件事：返回 false 通常意味着表达式有问题，返回空的 DOMNodeList 则更可能是命名空间、路径或输入结构不匹配。

用 DOMXPath::query 读取目标节点

拿到 DOMNodeList 后，再把它当成结果集合处理，而不要在 XPath 字符串里拼接用户提供的标签名。下面的函数只接受已经解析好的文档，返回代码和文本组成的数组，方便后续业务继续使用。

documentElement;
    if ($root === null || $root->namespaceURI === null) {
        // 没有命名空间时不套用 ns 前缀，直接返回空结果交给调用方判断。
        return [];
    }

    $xpath = new DOMXPath($dom);
    // 固定查询前缀，动态绑定文档实际使用的命名空间 URI。
    $xpath->registerNamespace('ns', $root->namespaceURI);
    $nodes = $xpath->query('//ns:catalog/ns:item');
    if ($nodes === false) {
        // 将 XPath 语法错误转换成业务异常，避免静默返回错误数据。
        throw new RuntimeException('无法执行节点查询');
    }

    $items = [];
    foreach ($nodes as $node) {
        if (!$node instanceof DOMElement) {
            // DOMNodeList 可能包含非元素节点，读取属性前先确认类型。
            continue;
        }

        $items[] = [
            'code' => $node->getAttribute('code'),
            'name' => trim($node->textContent),
        ];
    }

    return $items;
}

我更倾向于让函数从文档根节点动态取 URI，而不是把 urn:demo:catalog 写死在业务方法里。这样同一套选择逻辑可以处理 URI 不同但结构相同的 XML；如果业务要求只接受某个固定协议，再额外比较 URI 并明确抛出异常。

默认命名空间和显式前缀要分开理解

如果 XML 写成 ，元素属于默认命名空间，XPath 仍然不能写成 //catalog/item。XPath 里的无前缀名称表示“没有命名空间的元素”，不会自动指向 XML 的默认命名空间。

如果 XML 改成下面这样，原文出现了 c 前缀，但查询侧仍可以绑定成 ns。重要的是 URI 相同，而不是两个前缀的字面值相同。

DOM

registerNamespace('ns', 'urn:demo:catalog');
$nodes = $xpath->query('//ns:catalog/ns:item');

因此，排查时要把“XML 里的前缀”“元素的 namespaceURI”“XPath 查询侧的前缀”当成三个概念。前缀只是表达式中的可读别名，URI 才是命名空间身份。

XPath 返回空结果时按这几个点排查

1. 先确认 XML 是否真的加载成功。检查 loadXML() 的返回值，不要拿空文档继续查询。
2. 再看根元素的 namespaceURI。如果是 null 或空字符串，说明当前文档可能没有命名空间，或者你取到的不是预期根元素。
3. 检查 XPath 每一级名称。命名空间 XML 中，路径里的元素名称通常都要使用已经注册的前缀。
4. 区分 false 和空节点列表。false 更接近表达式错误；空列表则要继续对照 URI、路径和 XML 层级。
5. 检查上下文节点。使用相对 XPath 时，确认传入的上下文节点属于同一个 DOMDocument，不要把另一个文档的节点混进来。

如果命名空间来自外部协议，建议把“允许的 URI”和“查询前缀”作为配置或常量集中管理。这样 XML 升级时只需要调整映射，不会让多个 XPath 字符串各自藏着一份容易过期的 URI。

官方手册与适用边界

本文使用 PHP 官方 DOM 文档中 DOMXPath、registerNamespace() 和 query() 的接口语义。需要继续确认参数、返回值或 PHP 版本差异时，可直接复制下面的官方地址打开：

• https://www.php.net/manual/en/class.domxpath.php
• https://www.php.net/manual/en/domxpath.register-namespace.php
• https://www.php.net/manual/en/domxpath.query.php
• https://www.php.net/manual/en/domdocument.loadxml.php

这套方法适合读取结构清晰的 XML 文档。若输入来自不可信来源，还要单独按照项目的 XML 安全策略处理外部实体、大小限制和错误日志；命名空间映射本身只解决“节点属于哪个名字空间、XPath 如何选中它”这一个问题。

我最后会保留的最小写法

回到最初的空结果问题，最小答案其实只有三句：从根元素取 namespaceURI，在 DOMXPath 上注册查询前缀，XPath 每一级元素都写这个前缀。前缀可以自定义，URI 不能猜。

documentElement;
if ($root === null || $root->namespaceURI === null) {
    throw new RuntimeException('缺少 XML 命名空间');
}

$xpath = new DOMXPath($dom);
// ns 是查询别名，绑定值必须来自 XML 实际的 namespaceURI。
$xpath->registerNamespace('ns', $root->namespaceURI);
$nodes = $xpath->query('//ns:catalog/ns:item');

if ($nodes === false) {
    // 查询失败时保留明确错误，不把它伪装成“没有数据”。
    throw new RuntimeException('XPath 查询失败');
}

为什么无前缀 XPath 查不到默认命名空间元素？

因为 XPath 中的无前缀元素名表示无命名空间节点。XML 的默认命名空间需要先绑定到 XPath 查询前缀，再用带前缀的路径匹配。

查询前缀必须和 XML 原文一致吗？

不必一致。查询前缀是 DOMXPath 对象上的别名，只要它绑定到目标元素实际使用的 namespaceURI，就可以与 XML 原文的前缀不同。

为什么要检查 query() 是否返回 false？

因为表达式解析失败与“表达式合法但没有匹配节点”是两种不同情况。先区分返回值，再去检查 URI、路径和输入结构，定位会更快。