PHP DOMDocument与XPath文本节点修改技巧

问题背景与挑战

在使用PHP的DOMDocument和DOMXPath对HTML文档进行处理时，一个常见的需求是查找文本节点中的特定短语，并将其包裹在新的HTML元素中（例如，标签）。开发者通常会使用preg_match_all结合PREG_OFFSET_CAPTURE来获取所有匹配项及其在文本中的偏移量，然后利用DOMText::splitText()方法来分割文本节点，插入新的元素。

然而，当一个文本节点中存在多个匹配项时，直接按照从前往后的顺序进行修改会导致一个棘手的问题：在处理完第一个匹配项并修改了DOM结构后，原文本节点的长度和内部偏移量会发生变化。这使得后续匹配项的原始偏移量变得无效，从而导致DOMText::splitText()方法在尝试分割一个已经不存在或结构已改变的节点时，返回false，进而引发“Call to a member function splitText() on bool”的致命错误。

原始代码示例中，foreach ($matches as $group)的迭代方式也存在问题，它会重复处理匹配项，加剧了错误。

解决方案：倒序迭代与正确匹配项处理

解决此问题的关键在于两点：

1. 正确解析preg_match_all的输出：preg_match_all在PREG_OFFSET_CAPTURE模式下，其结果 $matches 是一个多维数组。$matches[0] 包含了所有完整匹配的字符串及其偏移量，而$matches[1]等则包含捕获组的匹配。通常，我们只需要处理$matches[0]。
2. 倒序迭代匹配项：这是解决偏移量失效问题的核心策略。通过从文本节点的末尾向开头处理匹配项，每次修改都不会影响到尚未处理的、位于当前修改点之前的匹配项的相对位置和偏移量。

下面是经过优化和修正的PHP函数，它展示了如何正确地实现这一逻辑：

标签中。
 *
 * @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内容，确保UTF-8编码并添加包装器以供解析
        // LIBXML_HTML_NOIMPLIED 和 LIBXML_HTML_NODEFDTD 用于防止DOMDocument自动添加不必要的HTML/BODY标签
        $DOM->loadHTML("{$content}", LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);

        // 清除加载HTML时产生的错误
        libxml_clear_errors();

        // 初始化XPath处理器
        $XPath = new DOMXPath($DOM);

        // 检索所有文本节点，排除