如何替换DOCX文档页脚中的占位符？

问题原因 #

默认情况下，TemplateProcessor的setComplexValue方法仅扫描并替换文档主正文区域的占位符，页脚属于独立的XML节点（存储在文档的footer*.xml文件中），无法被默认逻辑识别。

解决方案 #

通过指定setComplexValue的第三个参数，明确告诉处理器要替换的目标区域为页脚（或指定类型的页脚）。

基础用法（替换普通页脚） #

修改原代码，添加目标区域参数即可：

use PhpOffice\PhpWord\TemplateProcessor;
use PhpOffice\PhpWord\Element\Table;
use PhpOffice\PhpWord\Style\TblWidth;

$templateProcessor = new TemplateProcessor('path to DOCX file.....');

$table = new Table(['unit' => TblWidth::AUTO]);

$table->addRow();
$table->addCell(null, [
    'borderTopColor' => 'ff0000',
    'borderTopSize' => 1,
    'borderRightColor' => 'ff0000',
    'borderRightSize' => 1,
    'borderLeftColor' => 'ff0000',
    'borderLeftSize' => 1,
])->addText('bla bla bla', ['Color' => 'ff0000']);

// 指定替换页脚中的占位符
$templateProcessor->setComplexValue(
    '{bla_bla_bla_placeholder}',
    $table,
    TemplateProcessor::TARGET_FOOTER
);

// 保存处理后的文档
$templateProcessor->saveAs('processed_document.docx');

处理特殊页脚（首页/奇偶页不同） #

如果文档设置了不同类型的页脚（如首页专属页脚、奇偶页分离页脚），需要分别指定对应的目标常量：

// 替换首页页脚
$templateProcessor->setComplexValue(
    '{bla_bla_bla_placeholder}',
    $table,
    TemplateProcessor::TARGET_FOOTER_FIRST
);

// 替换奇数页页脚
$templateProcessor->setComplexValue(
    '{bla_bla_bla_placeholder}',
    $table,
    TemplateProcessor::TARGET_FOOTER_ODD
);

// 替换偶数页页脚
$templateProcessor->setComplexValue(
    '{bla_bla_bla_placeholder}',
    $table,
    TemplateProcessor::TARGET_FOOTER_EVEN
);

注意事项 #

1. 确保PhpWord版本支持目标区域参数：该特性在PhpWord 0.18.0及以上版本可用，旧版本需先升级。
2. 页脚占位符格式需与正文一致：占位符{bla_bla_bla_placeholder}在页脚中需保持完整，无额外格式干扰。
3. 保存文档前需确认所有目标页脚都已处理完毕。

内容的提问来源于stack exchange，提问作者Mister X