如何在 OpenTBS 中正确动态替换 Word 文档中的图片

opentbs 无法直接通过 url 替换图片，因其底层依赖 `file_exists()` 和 `filesize()` 等本地文件函数，而这些函数对 http url 返回 false；需先将远程图片下载为临时文件，再交由 opentbs 插入。

OpenTBS 的 [field;ope=changepic] 指令看似支持 URL，实则内部调用 file_exists() → filesize() → file_get_contents() 三步验证与读取。尽管 PHP 官方文档注明 file_exists() 和 filesize() “理论上” 支持 HTTP 流封装器，但实际绝大多数生产环境（尤其是禁用 allow_url_fopen 或使用 curl 作为默认流处理器时）中，这两个函数对 URL 均返回 false，导致 OpenTBS 提前终止图片插入流程——这正是你看到文字正常渲染、图片却始终显示为原始占位图的根本原因。

✅ 正确做法：预下载图片为临时文件，再传入 OpenTBS

以下为推荐的健壮实现方案（含错误处理与资源清理）：

function downloadImageToTemp($url) {     $content = file_get_contents($url);     if ($content === false) {         throw new Exception("Failed to fetch image from URL: $url");     }      // 自动推断 MIME 类型并设置扩展名     $finfo = finfo_open(FILEINFO_MIME_TYPE);     $mimeType = finfo_buffer($finfo, $content);     finfo_close($finfo);      $ext = match($mimeType) {         'image/jpeg', 'image/jpg' => '.jpg',         'image/png' => '.png',         'image/gif' => '.gif',         'image/webp' => '.webp',         default => '.bin'     };      $tempFile = tempnam(sys_get_temp_dir(), 'tbs_img_') . $ext;     if (file_put_contents($tempFile, $content) === false) {         throw new Exception("Failed to write temporary image file: $tempFile");     }      return $tempFile; }  // 使用示例 $imgs = []; foreach ([     ['url' => 'http://192.168.0.100/photo1.jpg', 'txt' => 'Sample 1'],     ['url' => 'https://example.com/photo2.png', 'txt' => 'Sample 2'] ] as $item) {     try {         $tempPath = downloadImageToTemp($item['url']);         $imgs[] = [             'url'  => $tempPath, // ✅ 传入本地临时路径，非 URL             'txt'  => $item['txt']         ];     } catch (Exception $e) {         error_log("Image download failed: " . $e->getMessage());         // 可选：跳过该条目，或提供默认占位图路径         continue;     } }  // 合并数据块（注意：模板中 [imgs.url;ope=changepic] 将自动识别本地路径） $OOo->MergeBlock('imgs', $imgs);  // ⚠️ 关键：在 Show() 之后、脚本结束前清理临时文件 register_shutdown_function(function() use ($imgs) {     foreach ($imgs as $img) {         if (!empty($img['url']) && is_file($img['url'])) {             @unlink($img['url']);         }     } });  $OOo->Show(OPENTBS_DOWNLOAD, 'report.docx');

? 重要注意事项：

• 模板中无需修改，保持 [imgs.url;ope=changepic] 即可，OpenTBS 会自动识别 .jpg/.png 等扩展名并嵌入二进制图片；
• 务必启用 register_shutdown_function() 或手动 unlink() 临时文件，避免磁盘空间泄漏；
• 若服务器限制外网访问，需确保 PHP 进程可访问目标图片 URL（检查防火墙、DNS、allow_url_fopen 配置）；
• 对于高并发场景，建议结合内存缓存（如 APCu）避免重复下载同一图片。

此方案完全绕过 OpenTBS 对 URL 的兼容性缺陷，稳定可靠，是当前社区公认的最佳实践。