PHP 8.4 Dom\HTMLDocument 怎么替换旧 DOMDocument：HTML5 解析与迁移边界

把一段后台编辑器 HTML 存进数据库前，PHP 程序通常要先解析标题、段落和链接。旧代码多半是 DOMDocument::loadHTML()，但它并不是按现代 HTML5 规则设计的：遇到没有完整文档骨架、模板元素或编码声明时，节点结构可能和浏览器看到的结果不一致。PHP 8.4 的 Dom\\HTMLDocument::createFromString() 提供了新的迁移入口，重点不是把类名机械替换掉，而是先确认命名空间、HTML 命名空间和输出结构。

先复现旧解析器与浏览器结果不一致的现场

假设运营提交了一段只有 main 和 article 的片段。旧代码直接调用 loadHTML() 后，PHP 会补出文档结构；这不一定是错误，但后续 XPath 或 CSS 选择器如果把“补出来的节点”当成业务节点，就会让数量统计和预览结果产生偏差。

$source = '
PHP 8.4
';

$document = \Dom\HTMLDocument::createFromString($source);
$articles = $document->getElementsByTagName('article');

echo $articles->length, PHP_EOL;
echo trim($articles->item(0)->textContent), PHP_EOL;
echo $document->saveHtml(), PHP_EOL;

这里先观察三个结果：元素集合是否只包含业务文章、文本节点是否保留、序列化后是否出现预期的 html、head 和 body。不要只用“字符串包含”判断解析成功，因为那无法证明节点树可遍历。

用 createFromString 明确 HTML5、编码和命名空间

createFromString() 的第一个参数是 HTML 字符串，第二个参数接收按位组合的 libxml 选项，第三个参数可覆盖编码推断。对于 UTF-8 的后台内容，建议在入口处统一编码，并在测试里把带中文的文本节点纳入断言。

新 API 的返回值是 Dom\\HTMLDocument。如果旧代码依赖全局命名空间的 DOMDocument、DOMXPath 或属性名，迁移时应分开改动，先让解析器和节点访问各自有回归结果。

命名空间变化为什么会让选择器突然查不到节点

HTML5 文档默认带有 HTML 命名空间。代码从旧 DOM API 迁到新 API 后，如果 XPath 仍然写成无前缀的 //article，查询结果可能为空；这不是文章节点消失，而是查询条件没有表达命名空间。更稳妥的做法是先读取实际节点的 namespaceURI，再决定给 XPath 注册前缀，或者在充分理解影响后传入 Dom\\HTML_NO_DEFAULT_NS。

$document = \Dom\HTMLDocument::createFromString($source);
$article = $document->getElementsByTagName('article')->item(0);

if ($article === null || trim($article->textContent) === '') {
    throw new RuntimeException('article 节点为空');
}

echo $article->namespaceURI, PHP_EOL;
echo trim($article->textContent), PHP_EOL;

如果项目使用 CSS 选择器库或 XPath 封装层，迁移验收要覆盖“找到一个节点”“找到多个节点”“找不到节点”三种状态。不要为了让旧断言立刻变绿就全局关闭命名空间，那可能掩盖其他 HTML5 行为变化。

给 PHP 8.3 及更早环境保留可控回退

Dom\\HTMLDocument 是 PHP 8.4 的能力，线上如果仍有 PHP 8.3 FPM，就需要在运行时做能力判断。回退分支可以继续调用 DOMDocument::loadHTML()，但要在备注和测试中明确：这条路径不是 HTML5 解析等价物，结果只能作为兼容保底。

function parseHtml(string $source): object
{
    if (class_exists(\Dom\HTMLDocument::class)) {
        return \Dom\HTMLDocument::createFromString($source);
    }

    $legacy = new \DOMDocument();
    $legacy->loadHTML($source, LIBXML_NOERROR | LIBXML_NOWARNING);
    return $legacy;
}

部署前至少在 PHP 8.4 和 PHP 8.3 各跑一组相同输入，记录节点数量、文章文本和序列化结果。若两条路径的差异会影响摘要、链接或审计字段，就不要把升级当成纯依赖替换，而要把结果差异纳入发布说明。

迁移完成后用四个检查点收口

1. 检查类是否存在：PHP 8.4 使用 Dom\\HTMLDocument，旧版本明确进入回退分支。
2. 检查节点树：中文文本、嵌套 article、属性和空节点都要有断言。
3. 检查查询方式：确认默认命名空间是否存在，XPath 或选择器是否按实际节点树工作。
4. 检查输出：比较 saveHtml() 结果，确认没有把解析器补出的结构误当成业务内容。

这样迁移的价值是把 HTML5 解析能力和兼容风险拆开管理。新代码可以使用更符合标准的文档模型，旧环境也能继续运行；真正需要上线前决定的，是业务是否接受两条解析路径在边界 HTML 上存在差异。

常见问题

PHP 8.4 的 Dom\HTMLDocument 能直接替换 DOMDocument 吗？

不能保证直接替换。它们的 API、命名空间和 HTML5 解析行为不同，应先覆盖节点树、选择器和序列化结果，再逐段迁移。

createFromString() 的第三个参数什么时候需要传？

当输入编码已由上传或接口协议明确给出时可以传入；如果省略，解析器会尝试判断编码，但输入本身必须先在边界层保持一致。

为什么 getElementsByTagName() 能找到节点，XPath 却找不到？

常见原因是 XPath 没有处理 HTML 命名空间。先查看节点的 namespaceURI，再注册前缀或评估是否真的需要关闭默认命名空间。

PHP 8.3 项目能使用 Dom\HTMLDocument 吗？

不能把它当作内置类使用。应保留 DOMDocument::loadHTML() 回退，并在升级到 PHP 8.4 后重新验证 HTML5 边界结果。