问题背景：DOM文本节点多次修改的挑战
在网页内容处理中，我们经常需要识别并修改特定的文本片段，例如将所有出现的品牌名称用标签包裹起来。PHP的DOMDocument和XPath提供了强大的能力来实现这一点。然而，当一个文本节点中存在多个匹配项，并且我们尝试使用DOMText::splitText()方法逐一修改它们时，一个常见的陷阱是，第一次修改会改变文本节点的内部结构，从而使得后续匹配项的偏移量失效，导致splitText()调用失败并抛出Fatal error: Uncaught Error: Call to a member function splitText() on bool错误。
具体来说，DOMText::splitText(offset)方法会在指定偏移量处将当前文本节点一分为二，返回一个新的文本节点（从偏移量开始的部分）。如果我们在一个文本节点上连续进行多次splitText()操作，并且每次操作都基于原始文本的偏移量，那么在第一次splitText()之后，原始文本节点的长度和内容都已改变，后续的偏移量将不再准确，甚至可能指向一个不再存在的文本部分，导致splitText()返回false，进而引发错误。
解决方案：逆序遍历与正确的匹配结果处理
要解决此问题，我们需要采取两种关键策略：
- 正确解析preg_match_all的结果： preg_match_all函数返回的$matches数组结构包含多个维度。对于我们关心的完整匹配字符串及其偏移量，通常位于$matches[0]中。不正确的遍历（例如，foreach ($matches as $group)）可能会导致重复处理或处理不正确的数据。
- 逆序遍历匹配项： 这是解决偏移量失效问题的核心。如果我们从文本节点的末尾向开头处理匹配项，每次修改（例如，将文本节点拆分并插入）只会影响当前修改点“之前”的DOM结构。这意味着，对于尚未处理的、位于当前修改点“之后”的匹配项，它们的偏移量仍然相对于原始文本节点是准确的。
详细步骤与示例代码
以下是基于原始问题的代码，并应用上述解决方案后的修正版本。我们将专注于foreach ($text as $node)循环内部的修改逻辑。
立即学习“PHP免费学习笔记（深入）”；
/**
* Automatically wrap various forms of CCJM in a class for branding purposes
*
* @param string $content
* @return string
*/
function ccjm_branding_filter(string $content): string {
if (! (is_admin() && ! wp_doing_ajax()) && $content) {
$DOM = new DOMDocument();
/**
* Use internal errors to get around HTML5 warnings
*/
libxml_use_internal_errors(true);
/**
* Load in the content, with proper encoding and an `` wrapper required for parsing
*/
$DOM->loadHTML("{$content}", LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
/**
* Clear errors to get around HTML5 warnings
*/
libxml_clear_errors();
/**
* Initialize XPath
*/
$XPath = new DOMXPath($DOM);
/**
* Retrieve all text nodes, except those within scripts
*/
$text = $XPath->query("//text()[not(parent::script)]");
foreach ($text as $node) {
/**
* Find all matches, including offset
* PREG_OFFSET_CAPTURE 捕获匹配项的偏移量
*/
preg_match_all("/(C\.? ?C\.?(?:JM| Johnson (?:&|&|&|and) Malhotra)(?: Engineers, LTD\.?|, P\.?C\.?)?)/i", $node->textContent, $matches, PREG_OFFSET_CAPTURE);
/**
* 确保有匹配项才进行处理
* 逆序遍历匹配项，以避免DOM修改导致的偏移量失效问题
* $matches[0] 包含所有完整匹配的字符串及其偏移量
*/
$group = array_reverse($matches[0]); // 关键：逆序遍历 $matches[0]
foreach ($group as $match) {
/**
* Determine the offset and the length of the match
*/
$offset = $match[1];
$length = strlen($match[0]);
/**
* Isolate the match and what comes after it
* splitText(offset) 会将当前节点在 offset 处分割，
* 并返回从 offset 开始的新节点。
* 原节点会保留 offset 之前的部分。
*/
$word = $node->splitText($offset);
/**
* 再次调用 splitText，从 $word 节点的开头（即原匹配项的开头）
* 分割出匹配项本身。
* $after 节点将包含匹配项之后的部分。
*/
$after = $word->splitText($length);
/**
* Create the wrapping span
*/
$span = $DOM->createElement("span");
$span->setAttribute("class", "__brand");
/**
* Replace the word (匹配到的文本节点) with the span,
* and then re-insert the word within it
*/
$word->parentNode->replaceChild($span, $word);
$span->appendChild($word);
}
}
/**
* Save changes, remove unneeded tags
* 提取 body 内容，去除 html/body 包装
*/
$content = implode(array_map([$DOM->documentElement->ownerDocument, "saveHTML"], iterator_to_array($DOM->documentElement->childNodes)));
// 如果需要更精确地获取内的内容，可以查询body节点
// $body = $XPath->query('//body')->item(0);
// if ($body) {
// $content = '';
// foreach ($body->childNodes as $child) {
// $content .= $DOM->saveHTML($child);
// }
// }
}
return $content;
}
// add_filter("ccjm_final_output", "ccjm_branding_filter"); // 如果是WordPress环境，则需要此行代码修改要点：
- 移除冗余循环： 原代码中的 foreach ($matches as $group) 是不必要的，因为$matches数组的第一个元素$matches[0]已经包含了所有完整的匹配项及其偏移量。
- 逆序遍历： 将$matches[0]通过array_reverse()函数进行逆序处理。foreach ($group as $match)现在会从文本的末尾匹配项开始处理。
- 移除break： 原代码中的break语句导致只处理了每个文本节点的第一个匹配项，现在可以安全移除，以确保所有匹配项都被处理。
结果示例
使用提供的示例内容：
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.
经过修正后的代码处理，输出结果将如下所示，所有匹配的短语都被正确地包裹在标签中：
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.
注意事项与总结
- DOM操作的原子性： 每次对DOM树的修改都可能影响其结构。当涉及到文本节点的拆分和替换时，这一点尤为重要。
- splitText()的返回类型： 务必检查splitText()的返回值。如果偏移量无效，它可能返回false，导致后续对返回值的操作（如$word->splitText($length)）失败。
- 性能考量： 对于非常大的HTML文档和大量的文本节点，DOMDocument的操作可能会消耗较多的内存和CPU资源。在生产环境中，应进行性能测试。
- HTML解析： DOMDocument::loadHTML()在解析非标准或格式不佳的HTML时可能会遇到问题。使用libxml_use_internal_errors(true)和libxml_clear_errors()是一种常见的处理方式，但仍需确保输入HTML的质量。
通过采用逆序遍历匹配项的策略，我们能够有效地规避PHP DOMDocument在处理单个文本节点内多个修改时所面临的偏移量失效问题，从而实现稳健且准确的文本内容转换。理解DOM操作的底层机制是编写高效且无错代码的关键。
