Laravel合并审批附件：让文件、页范围和输出顺序保持一致

审批单、证明材料和补充附件要合成一份PDF。系统不仅要合并文件，还要让用户指定的顺序、页范围与实际输出一致。

可下载教学输入、实际产物与示例代码对照检查。包内不含API密钥、SDK许可或SDK安装包。

从附件记录建立输入

后端先确认当前用户能读取各附件，并固定输入版本。清单至少保留附件ID、位置和页范围。下载缺失或文件版本变化时，返回具体问题，不自动跳过后仍标记为完整材料。

下面用两份服务端教学文件演示请求结构。真实路径由后端附件记录解析，不能由浏览器提交任意绝对路径。

先用接口请求做对照

下载教学包并解压，在包含inputs目录的位置运行。服务端环境变量COMPDF_API_KEY应已配置，不把实际密钥写进文章或浏览器：

curl --fail-with-body --request POST \
  'https://api-server.compdf.com/server/v2/process/pdf/merge' \
  --header "x-api-key: $COMPDF_API_KEY" \
  --form 'file=@inputs/appendix-a.pdf' \
  --form 'file=@inputs/appendix-b.pdf' \
  --form 'filePageRanges=all' \
  --form 'filePageRanges=1' \
  --form 'outputFileName=approval.pdf' \
  --output response.json

先检查JSON的业务状态，成功后按结果地址下载，再与教学包中的outputs/merge-repeated.pdf比较。这条接口请求和正反页序已有实际结果；下文Laravel片段是对同一multipart请求的接入写法，此轮没有运行完整Laravel应用。

顺序与页范围一起提交

ComPDF合并接口按文件提交顺序处理，filePageRanges与文件一一对应，页码从1开始。下面使用Laravel HTTP Client发送两份文件；$pathA、$pathB来自已验证的本地输入，$key来自服务端配置。

use Illuminate\Support\Facades\Http;

$a = fopen($pathA, 'rb');
$b = fopen($pathB, 'rb');
if ($a === false || $b === false) {
    if (is_resource($a)) fclose($a);
    if (is_resource($b)) fclose($b);
    throw new RuntimeException('读取教学附件失败');
}
try {
    $response = Http::withHeaders(['x-api-key' => $key])
        ->timeout(120)
        ->attach('file', $a, 'application.pdf')
        ->attach('file', $b, 'proof.pdf')
        ->post('https://api-server.compdf.com/server/v2/process/pdf/merge', [
            ['name' => 'filePageRanges', 'contents' => 'all'],
            ['name' => 'filePageRanges', 'contents' => '1'],
            ['name' => 'outputFileName', 'contents' => 'approval.pdf'],
        ]);
    $response->throw();
    $payload = $response->json();
} finally {
    if (is_resource($a)) fclose($a);
    if (is_resource($b)) fclose($b);
}

这里合并A的全部页和B的第一页。120秒是示例客户端超时，不代表服务处理承诺。示例使用海外节点；实际节点、请求模式和数组编码应按当前账号及接口确认。

throw()只检查HTTP错误。继续核对$payload中的业务状态、错误及结果地址；接口返回结构以当前版本为准。需要密码时，密码列表也必须与文件清单对齐，不记录到日志。

请求字段也要用实际结果验证

本轮直接调用API时，带方括号的filePageRanges[]写法没有通过；改成重复的filePageRanges字段后，输出为3页，顺序是A第1页、A第2页、B第1页。反向提交B第1页、A全部页，输出顺序也相应改变。

因此上面的请求按重复字段组织，不把PHP数组名称原样当成接口字段。不同客户端最终发出的multipart字段仍需核对；本轮API线格式和产物已验证，Laravel运行环境尚需单独检查。

图：本轮教学输入的实际检查结果；适用范围与未通过项见正文。

检查输出顺序

下载结果后，检查总页数以及A结束、B开始的位置。教学文件的首页可分别写上A、B，便于检查；总页数相同不代表顺序正确。

把顺序改成B、A，再执行一次，确认输出也相应改变。最后用缺失文件测试失败提示，确认不会交付少一份附件的结果。

归档时保存有序输入版本清单与最终文件。用户替换附件或调整顺序时，生成新结果。审批系统需要持续执行此操作时，可在开发者平台用授权样本评估接口，先验证页范围与输出，再增加队列和批量能力。

本作品采用《CC 协议》，转载必须注明作者和本文链接