本教程深入探讨了在使用 php domDocument 的 splitText 方法对文本节点进行多次修改时，因 DOM 结构变化导致的偏移量错误。文章详细分析了问题根源，并提供了一种高效且可靠的解决方案：通过反向迭代匹配项，确保每次修改都不影响后续操作的准确性，从而成功实现对所有目标文本的封装。
1. 引言：使用 DOMDocument 封装文本
在 web 开发中，我们经常需要对 html 内容中的特定文本模式进行查找和修改，例如为特定品牌名称添加样式或链接。php 的 domdocument 结合 domxpath 提供了一套强大的工具来解析和操作 html 结构。然而，当需要在一个文本节点内多次修改（例如，将多个匹配项封装到 <span> 标签中）时，我们可能会遇到一些意料之外的问题，尤其是涉及到 domtext::splittext() 方法时。
2. 问题分析：splitText 与偏移量错误
假设我们的目标是找到文本节点中所有匹配特定正则表达式的短语，并将它们用 <span> 标签包裹起来。一个常见的思路是：
- 使用 preg_match_all 查找所有匹配项及其在文本内容中的偏移量。
- 遍历这些匹配项。
- 对于每个匹配项，使用 DOMText::splitText($offset) 将文本节点分割成两部分：匹配项之前的内容和匹配项及其之后的内容。
- 再次使用 splitText($Length) 将匹配项从第二部分中分离出来。
- 创建一个新的 <span> 元素，将匹配项（现在是一个独立的文本节点）插入其中，然后用 <span> 替换原有的匹配项文本节点。
然而，这种从左到右（从前到后）的顺序修改方式，在处理同一个文本节点内的多个匹配项时，会导致一个常见的错误：Fatal Error: Uncaught Error: Call to a member function splitText() on bool。
问题根源：
DOMText::splitText() 方法在被调用时，会修改原始文本节点的内容，并返回一个新的文本节点。例如，对一个文本节点 $node 调用 $word = $node->splitText($offset) 后，$node 的内容会被截断到 $offset 处，而 $word 则包含了从 $offset 开始的剩余文本。这意味着原始文本节点的结构和内容已经改变。
立即学习“PHP免费学习笔记（深入）”；
如果我们在第一次 splitText 操作后，继续使用为原始未修改文本计算出的偏移量来处理同一个 $node 中的后续匹配项，这些偏移量将不再准确。因为 DOM 结构已经发生了变化，原始的偏移量已经失效，导致 splitText 无法找到正确的位置，甚至可能在内部操作中返回 false，从而引发上述错误。
3. 解决方案：反向迭代匹配项
解决此问题的关键在于改变处理匹配项的顺序。如果我们从右到左（从后到前）地修改文本节点，那么每次修改都只会影响当前匹配项及其之后的内容。对于尚未处理的、位于当前匹配项“之前”的匹配项，它们的偏移量将保持不变，因为它们所处的文本位置没有受到影响。
具体步骤：
- 获取所有匹配项及其偏移量。
- 将这些匹配项按照它们在文本中的起始偏移量进行降序排序（即从文本末尾向文本开头排序）。
- 按照这个降序顺序遍历匹配项，并执行 splitText 和封装操作。
4. 示例代码与优化
以下是基于原始问题代码的优化版本，它采用了反向迭代策略，并修正了 preg_match_all 的遍历逻辑。
<?php /** * 自动将特定短语封装到带有特定类的 span 标签中 * * @param string $content HTML内容字符串 * @return string 处理后的HTML内容字符串 */ function ccjm_branding_filter(string $content): string { // 仅在非管理后台且非 AJAX 请求时执行，并确保内容不为空 if (! (is_admin() && ! wp_doing_ajax()) && $content) { $DOM = new DOMDocument(); // 启用内部错误处理以抑制 html5 警告 libxml_use_internal_errors(true); // 加载内容，确保正确的编码和 HTML 包装器 // LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD 用于避免 DOMDocument 自动添加额外的标签 $DOM->loadHTML("<?xml encoding='utf-8' ?><html>{$content}</html>", LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD); // 清除加载过程中产生的错误 libxml_clear_errors(); // 初始化 XPath $XPath = new DOMXPath($DOM); // 检索所有文本节点，排除 <script> 标签内的文本 $textNodes = $XPath->query("//text()[not(parent::script)]"); foreach ($textNodes as $node) { // 查找所有匹配项，包括偏移量 // PREG_OFFSET_CAPTURE 返回每个匹配项及其在字符串中的偏移量 preg_match_all("/(C.? ?C.?(?:JM| Johnson (?:&|&|&|and) Malhotra)(?: Engineers, LTD.?|, P.?C.?)?)/i", $node->textContent, $matches, PREG_OFFSET_CAPTURE); // 检查是否有匹配项 if (empty($matches[0])) { continue; // 没有匹配项，跳过当前节点 } /** * 关键优化：反向迭代匹配项 * preg_match_all 返回的 $matches[0] 包含所有完整匹配项及其偏移量。 * 通过 array_reverse() 从后往前处理，避免 DOM 修改导致的偏移量失效问题。 */ $reversedMatches = array_reverse($matches[0]); foreach ($reversedMatches as $match) { // 确定匹配项的偏移量和长度 $offset = $match[1]; $length = strlen($match[0]); /** * 隔离匹配项及其之后的内容 * splitText($offset) 会将 $node 截断，并返回一个新节点包含从 $offset 开始的文本。 * $word 此时是包含匹配项及其之后内容的文本节点。 */ $word = $node->splitText($offset); /** * 再次 splitText，将匹配项本身从 $word 中分离出来。 * $after 包含了匹配项之后的内容，而 $word 现在只包含匹配项。 */ $after = $word->splitText($length); // 创建封装用的 span 标签 $span = $DOM->createElement("span"); $span->setAttribute("class", "__brand"); // 用 span 替换原始的匹配项文本节点，并将匹配项重新插入到 span 中 $word->parentNode->replaceChild($span, $word); $span->appendChild($word); } } // 保存修改后的 HTML 内容，并移除 DOMDocument 自动添加的 <html> 标签 // 通过迭代 documentElement 的子节点并分别保存 HTML，可以有效去除外层包装 $content = implode(array_map([$DOM->documentElement->ownerDocument, "saveHTML"], iterator_to_array($DOM->documentElement->childNodes))); } return $content; } // 示例用法（如果是在 WordPress 环境中） // add_filter("ccjm_final_output", "ccjm_branding_filter"); // 示例内容 $sampleContent = 'C.C. Johnson & Malhotra, P.C. (CCJM) was an integral member of a large Design Team for a 16.5-mile-long Public-Private Partnership (P3) Purple Line Project. The east-west light rail system extends from New Carrollton in PG County, MD to Bethesda in MO County, MD with 21 stations and one short tunnel. CCJM was Engineer of Record (EOR) for the design of eight (8) Bridges and design reviews for 35 transit/highway bridges and over 100 retaining walls of different lengths/types adjacent to bridges and in areas of cut/fill. CCJM designed utility structures for 42,000 LF of relocated water mains and 19,000 LF of relocated sewer mains meeting Washington Suburban Sanitary Commission (WSSC), Md Dept of Transportation (MDOT) MTA, and Local Standards.'; echo ccjm_branding_filter($sampleContent); ?>
代码解释：
- preg_match_all 结果处理： 修正了原代码中 foreach ($matches as $group) 的错误用法。preg_match_all 配合 PREG_OFFSET_CAPTURE 时，$matches[0] 包含所有完整匹配项的 [匹配字符串, 偏移量] 数组。我们应该直接处理这个数组。
- array_reverse($matches[0])： 这是解决问题的核心。通过反转匹配项数组，我们确保了在处理文本节点时，总是从最后一个匹配项开始，向第一个匹配项倒序处理。这样，任何对 DOM 的修改都不会影响到尚未处理的、位于其之前的匹配项的偏移量。
- splitText 逻辑： $node->splitText($offset) 返回的是从 $offset 处开始的新节点。然后 $word->splitText($length) 再次分割，将匹配项本身隔离出来。
- DOM 操作： 创建 <span> 元素，替换原始文本节点，并将隔离出的匹配项文本节点重新添加到 <span> 中。
5. 注意事项与最佳实践
- 错误处理： 使用 libxml_use_internal_errors(true) 和 libxml_clear_errors() 是处理 HTML5 兼容性问题和抑制 DOMDocument 警告的良好实践。
- HTML 结构： DOMDocument::loadHTML() 需要一个完整的 HTML 结构才能正确解析，即使是片段也最好用 <html> 标签包裹。LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD 可以防止 DOMDocument 自动添加 <!DOCTYPE> 或 <body> 标签。
- 输出清理： 在保存修改后的内容时，需要注意 DOMDocument 可能会添加额外的 <html> 或 <body> 标签。示例代码中的 implode(array_map([$DOM->documentElement->ownerDocument, “saveHTML”], iterator_to_array($DOM->documentElement->childNodes))) 是一种有效移除这些不必要包装的方法。
- 性能考量： 对于非常大的 HTML 文档和大量的文本节点，频繁的 DOM 操作可能会影响性能。在这种情况下，可以考虑其他非 DOM 的字符串替换方法（如 preg_replace_callback），但它们可能无法处理复杂的 HTML 结构（例如避免修改属性值或脚本内容）。对于需要精确 DOM 结构感知的场景，DOMDocument 仍是首选。
- 正则表达式： 确保你的正则表达式能够准确匹配目标短语，并且不会意外匹配到 HTML 标签或属性值中不应修改的部分。在示例中，//text()[not(parent::script)] 已经排除了脚本内容。
6. 总结
通过理解 DOMText::splitText() 的工作原理及其对 DOM 结构的影响，并采用反向迭代匹配项的策略，我们可以有效解决在 PHP DOMDocument 中对文本节点进行多次修改时遇到的偏移量错误。这种方法不仅保证了操作的准确性，也提升了代码的健壮性，是处理此类 DOM 操作的专业实践。
