在日常的Web应用开发中，处理PDF文件是一个常见的需求。想象一下这样的场景：你需要为用户生成一份年度报告，这份报告由多个独立的PDF部分组成——封面、目录、数据分析图表、结论等。或者，你的系统允许用户上传多个PDF附件，而你需要将这些附件合并成一个单一的文档供后续处理或下载。
起初，我尝试过一些手动合并PDF的方法，但那不仅耗时，而且在面对大量文件时几乎不可行。转向程序化解决方案后，我发现虽然市面上有一些PHP的PDF处理库，但它们往往API复杂、配置繁琐，或者对底层PDF知识要求较高。特别是当需要精确控制合并文件的页码范围、处理不同方向（横向/纵向）的页面时，更是让人头疼。我需要一个既强大又易用的工具，来简化这个流程。
直到我发现了 tomsgu/pdf-merger 这个Composer库。它就像是为解决这类问题而生，提供了一个简洁的API，将复杂的PDF合并逻辑封装起来，让开发者能够以极低的门槛实现高效的PDF合并。
tomsgu/pdf-merger：PDF合并的利器
tomsgu/pdf-merger 是一个基于 setasign/fpdi 和 fpdf 库的PHP PDF合并封装器，专为PHP 7.2 及更高版本设计。它的灵感来源于 clegginabox/pdf-merger，但提供了更现代和简洁的接口。如果你正在使用Symfony框架，甚至可以直接使用 tomsgu/pdf-merger-bundle，进一步简化集成。
立即学习“PHP免费学习笔记（深入）”；
安装与使用
首先，通过Composer将其安装到你的项目中：
composer require tomsgu/pdf-merger
安装完成后，你就可以在代码中轻松使用它了。以下是一个基本的示例，展示了如何合并多个PDF文件，并控制其页面和方向：
addPdf('document1.pdf', PdfFile::ALL_PAGES, PdfFile::ORIENTATION_PORTRAIT);
$pdfCollection->addPdf('document2.pdf', '1-4,9', PdfFile::ORIENTATION_LANDSCAPE);
$pdfCollection->addPdf('document3.pdf', '1-4,9', PdfFile::ORIENTATION_AUTO_DETECT);
$pdfCollection->addPdf('document4.pdf'); // 默认合并所有页面，自动检测方向
// 你甚至可以直接传递一个文件资源
$resource = fopen('document5.pdf', 'r');
if ($resource) {
$pdfCollection->addPdf($resource);
}
// 3. 初始化FPDI和PdfMerger
$fpdi = new Fpdi();
$merger = new PdfMerger($fpdi);
// 4. 执行合并操作
/**
* merge() 方法参数：
* - $pdfCollection: 包含所有待合并PDF文件的集合
* - $outputFilename: 输出文件的名称
* - $mode: 输出模式 (PdfMerger::MODE_FILE, MODE_DOWNLOAD, MODE_STRING, MODE_BROWSER)
* - $orientation: 默认页面方向，如果addPdf时未指定，将使用此方向
*/
try {
$merger->merge($pdfCollection, 'merged_output.pdf', PdfMerger::MODE_FILE, PdfFile::ORIENTATION_LANDSCAPE);
echo "PDF文件已成功合并到 merged_output.pdf\n";
} catch (\Exception $e) {
echo "合并PDF时发生错误: " . $e->getMessage() . "\n";
}
// 如果你传递了文件资源，记得关闭它
if (isset($resource) && is_resource($resource)) {
fclose($resource);
}
?>在这个例子中，我们首先创建了一个 PdfCollection 对象来管理所有待合并的PDF文件。addPdf 方法允许你灵活地指定每个PDF文件的路径、需要合并的页码范围（例如 '1-4,9' 表示第1到4页和第9页）以及页面方向。如果未指定页码，默认为 ALL_PAGES。
接着，我们实例化了 setasign\Fpdi\Fpdi 对象，并将其传递给 Tomsgu\PdfMerger\PdfMerger。最后，调用 merge 方法，传入PDF集合、输出文件名、输出模式（如 MODE_FILE 表示保存到文件，MODE_DOWNLOAD 表示直接下载，MODE_STRING 返回PDF内容字符串，MODE_BROWSER 在浏览器中显示）以及一个可选的默认页面方向。
优势与实际应用效果
tomsgu/pdf-merger 库的优势显而易见：
- API简洁直观： 封装了复杂的FPDI/FPDF操作，提供易于理解和使用的接口。
- 高度灵活性： 支持选择特定页码、处理不同页面方向，并提供多种输出模式，满足各种业务需求。
- 性能可靠： 基于业界成熟且广泛使用的FPDI和FPDF库，确保合并过程的稳定性和文件质量。
- 无需额外扩展： 纯PHP实现，无需依赖mbstring或iconv等PHP扩展，部署方便。
- 框架友好： 针对Symfony用户提供了专门的Bundle，简化了框架集成。
在实际应用中，tomsgu/pdf-merger 极大地提升了我的工作效率：
- 自动化报告生成： 我可以轻松地将系统生成的各种图表、表格PDF合并成一份完整的报告，并提供下载。
- 文档归档与整合： 对于需要将用户上传的多个合同、凭证等PDF文件合并成一个统一档案的需求，它表现得游刃有余。
- 电子书与手册制作： 快速将不同章节的PDF文件拼接成一本完整的电子书或产品手册。
总而言之，如果你在PHP项目中面临PDF合并的挑战，tomsgu/pdf-merger 绝对是一个值得尝试的解决方案。它以其简洁的API、强大的功能和可靠的性能，将复杂的PDF操作变得触手可及，让你能够专注于业务逻辑，而不是被繁琐的PDF处理细节所困扰。
