FPDI合并PDF智能适配页面方向与尺寸

本文详细介绍了如何使用PHP的FPDI库合并多个PDF文件，并解决了在合并过程中因页面方向和尺寸不匹配导致内容截断的问题。通过动态获取源PDF页面的模板尺寸和方向，我们能够确保合并后的文档准确无误地保留原始布局，从而提升文档处理的灵活性和用户体验。

在处理PDF文档时，尤其是在需要将多个用户上传的PDF文件合并成一个新文档的场景中，常常会遇到一个挑战：如果源PDF文件的页面方向（如纵向和横向）或尺寸不一致，简单地将它们合并到一个预设方向和尺寸的输出文档中，会导致部分内容被裁剪或显示不完整。本文将深入探讨如何利用FPDI库的强大功能，动态检测并适配源PDF页面的布局，从而实现无缝且准确的PDF合并。

理解问题：固定页面布局的局限性

传统的PDF合并方法，如果不对源页面进行分析，通常会为输出文档设置一个固定的页面方向和尺寸（例如A4纵向）。当遇到横向页面或尺寸不同的页面时，这些页面内容会被强制缩放或截断以适应输出文档的固定布局，导致信息丢失或排版混乱。

例如，以下是合并PDF时可能出现的原始问题代码片段，它没有考虑源页面的尺寸和方向：

// ... 文件收集逻辑 ...
$pdf = new \setasign\Fpdi\Fpdi();

foreach ($files as $file) {
    $pageCount = $pdf->setSourceFile($file);
    for ($i = 0; $i < $pageCount; $i++) {
        // 导入页面时未获取其尺寸信息
        $tpl = $pdf->importPage($i + 1, '/MediaBox');
        // 简单地添加新页面，默认可能是A4纵向
        $pdf->addPage();
        $pdf->useTemplate($tpl);
    }
}
$pdf->Output('F', $upload_folder . '/' . $pdf_name);

这段代码的问题在于，$pdf->addPage() 方法在没有参数的情况下，会使用FPDF（FPDI基于FPDF）默认的页面设置，通常是A4纵向。这对于所有纵向A4页面是没问题的，但对于横向页面或不同尺寸的页面，就会出现裁剪。

解决方案：动态适配页面布局

FPDI库提供了一种机制，允许我们导入源PDF页面作为模板，并获取该模板的详细尺寸信息，包括其方向。利用这些信息，我们可以在添加新页面时，动态地设置新页面的方向和尺寸，使其与源页面完全匹配。

核心步骤如下：

1. 导入页面并获取模板ID：使用importPage()方法导入源PDF的某一页，并获取一个模板ID。
2. 获取模板尺寸：使用getTemplateSize()方法，传入上一步获取的模板ID，即可获得一个包含页面宽度、高度和方向信息的数组。
3. 动态添加新页面：根据getTemplateSize()返回的信息，调用AddPage()方法，传入正确的方向和尺寸参数。
4. 使用模板：最后，将导入的模板内容放置到新添加的页面上。

示例代码

下面是实现动态适配页面布局的完整PHP代码示例：

setSourceFile($file);

        // 遍历源文件的每一页
        for ($pageNo = 1; $pageNo <= $pageCount; $pageNo++) {
            // 导入当前页面作为模板
            $templateId = $pdf->importPage($pageNo);

            // 获取导入页面的尺寸信息 (包括方向、宽度、高度)
            $size = $pdf->getTemplateSize($templateId);

            // 根据获取到的尺寸信息添加新页面
            // $size['orientation'] 将是 'P' (纵向) 或 'L' (横向)
            // $size 数组包含了 width 和 height
            $pdf->AddPage($size['orientation'], [$size['width'], $size['height']]);

            // 将导入的模板内容放置到新添加的页面上
            $pdf->useTemplate($templateId);

            // 可选：在页面上添加一些自定义内容，例如页脚或水印
            // $pdf->SetFont('Helvetica', '', 8);
            // $pdf->SetXY(5, 5);
            // $pdf->Write(8, '通过FPDI动态合并的页面');
        }
    } catch (\Exception $e) {
        error_log("处理文件 " . $file . " 时发生错误: " . $e->getMessage());
        // 可以选择在这里跳过当前文件或进行其他错误处理
    }
}

// 定义输出文件的路径和名称
$outputFileName = 'merged_document_dynamic.pdf';
$outputFilePath = __DIR__ . '/' . $outputFileName; // 输出到当前脚本所在目录

// 输出PDF文件到指定路径
// 'F' 表示将PDF保存为文件
$pdf->Output('F', $outputFilePath);

echo "PDF文件已成功合并并保存至: " . $outputFilePath;

?>

注意事项与最佳实践

1. FPDI/FPDF版本兼容性：确保您使用的FPDI和FPDF库是最新版本或兼容版本。getTemplateSize()方法在较旧的版本中可能不存在或行为不同。通常建议通过Composer安装setasign/fpdf和setasign/fpdi。
2. 错误处理：在实际生产环境中，务必对文件操作和PDF处理过程中可能出现的异常进行捕获和处理。例如，文件不存在、PDF文件损坏等情况都可能导致程序中断。
3. 性能考虑：合并大量或非常大的PDF文件可能会消耗较多的内存和CPU资源。如果需要处理海量文件，请考虑服务器性能、PHP内存限制（memory_limit）和执行时间限制（max_execution_time）。
4. 页面边距和缩放：useTemplate()方法默认会将模板内容放置在页面的左上角，并尽可能地填充整个页面。如果您需要对导入的页面进行缩放、定位或添加边距，useTemplate()方法还接受额外的参数来控制这些行为。例如：$pdf->useTemplate($templateId, $x, $y, $width, $height);。
5. 自定义内容：在useTemplate()之后，您可以像操作普通FPDF页面一样，继续添加文本、图片、线条等自定义内容，例如页眉、页脚、水印或批注。
6. 输出方式：$pdf->Output()方法有多种输出模式，例如I（直接在浏览器中显示）、D（作为下载附件）、F（保存到文件）和S（作为字符串返回）。根据您的需求选择合适的输出方式。

总结

通过动态获取源PDF页面的模板尺寸和方向，FPDI库提供了一种强大而灵活的方式来合并PDF文件，有效解决了因页面布局不一致导致的裁剪问题。这种方法不仅提升了合并文档的准确性和视觉效果，也极大地增强了PHP在PDF处理方面的能力，使其能够更好地适应各种复杂的文档生成和管理需求。掌握此技巧，将使您在开发涉及PDF合并功能的应用程序时更加得心应手。