PHPFPDI分页打印教程详解

在文章实战开发的过程中，我们经常会遇到一些这样那样的问题，然后要卡好半天，等问题解决了才发现原来一些细节知识点还是没有掌握好。今天golang学习网就整理分享《PHP FPDI 大型 PDF 分页打印教程》，聊聊，希望可以帮助到正在努力赚钱的你。

本文详细介绍了如何利用 PHP 的 FPDI 库高效地将大型单页 PDF 文档（如大幅面设计图或缝纫图案）分割成多个标准尺寸（如 Letter 或 A4）的小页面，以便于在普通打印机上分块打印并重新拼接。该方法避免了传统图像转换方式可能带来的质量损失和性能问题，通过直接操作 PDF 内容，确保输出质量和处理效率。

引言：大型 PDF 文档的打印挑战

在实际应用中，我们经常会遇到需要打印大幅面 PDF 文档（例如，尺寸为 24"x96" 的工程图纸或设计图案）的需求。然而，普通家用或办公打印机通常仅支持 Letter 或 A4 等标准尺寸纸张。为了解决这一问题，传统的做法是利用打印机驱动的“平铺打印”功能，或者借助第三方工具如 pdfposter。当这些选项不尽如人意时，开发者可能会考虑将 PDF 转换为图像，然后裁剪图像并使用 FPDF 等库生成新的 PDF。然而，这种方法存在明显的弊端：图像转换可能导致质量下降、文件体积增大，并且对内存消耗较大，尤其是在处理高分辨率或复杂图形时。

本文将介绍一种更为高效和专业的解决方案：利用 PHP 的 FPDI 库直接导入并操作 PDF 页面，从而实现无损、精确的页面分割与平铺打印。

解决方案核心：FPDI 的页面导入能力

FPDI（FPDF Document Importer）是 FPDF 的一个扩展，它允许开发者导入现有的 PDF 页面作为模板，然后在新的 FPDF 文档中对其进行操作，包括缩放、定位和裁剪。与将 PDF 转换为图像再处理的方法不同，FPDI 直接处理 PDF 内容，从而避免了图像转换带来的潜在问题。

其核心思想是：将原始的大型 PDF 页面视为一个整体模板，然后根据目标纸张尺寸，计算出需要分割的行数和列数。接着，为每个分割出的“小块”创建一个新的 PDF 页面，并将原始模板的相应区域（即当前“小块”对应的部分）精确地放置到新页面上。

实现步骤与示例代码

以下是使用 FPDI 实现大型 PDF 页面分割为多页打印的详细步骤和概念性代码示例：

1. 环境准备

首先，确保你的 PHP 环境中安装了 FPDF 和 FPDI 库。你可以通过 Composer 进行安装：

composer require setasign/fpdf
composer require setasign/fpdi

2. 核心逻辑实现

<?php

require_once('vendor/autoload.php'); // 引入 Composer 自动加载文件

use setasign\Fpdi\Fpdi;

/**
 * 将大型单页 PDF 分割为多个标准尺寸页面
 *
 * @param string $sourcePdfPath 原始大型 PDF 文件的路径
 * @param string $outputPdfPath 输出的分割后 PDF 文件的路径
 * @param float $targetPageWidth 目标页面的宽度 (单位: mm)
 * @param float $targetPageHeight 目标页面的高度 (单位: mm)
 */
function splitLargePdfForTiling(string $sourcePdfPath, string $outputPdfPath, float $targetPageWidth = 215.9, float $targetPageHeight = 279.4)
{
    // 创建一个新的 FPDI 实例
    $pdf = new Fpdi();

    // 导入原始 PDF
    $pageCount = $pdf->setSourceFile($sourcePdfPath);
    if ($pageCount === 0) {
        throw new Exception("无法读取源 PDF 文件或文件为空。");
    }

    // 假设原始 PDF 只有一页，获取其模板 ID
    $templateId = $pdf->importPage(1);

    // 获取原始页面的尺寸
    $originalPageSize = $pdf->getTemplateSize($templateId);
    $originalWidth = $originalPageSize['width'];
    $originalHeight = $originalPageSize['height'];

    // 计算需要平铺的行数和列数
    // 向上取整，确保所有内容都被覆盖
    $numCols = ceil($originalWidth / $targetPageWidth);
    $numRows = ceil($originalHeight / $targetPageHeight);

    echo "原始尺寸: {$originalWidth}x{$originalHeight} mm\n";
    echo "目标尺寸: {$targetPageWidth}x{$targetPageHeight} mm\n";
    echo "将分割为 {$numRows} 行 x {$numCols} 列\n";

    // 遍历所有需要生成的平铺页面
    for ($row = 0; $row < $numRows; $row++) {
        for ($col = 0; $col < $numCols; $col++) {
            // 添加新页面，尺寸为目标页面的尺寸
            // 默认方向为 Portrait (P)，如果目标页面是 Landscape (L) 需要调整
            $pdf->AddPage('P', [$targetPageWidth, $targetPageHeight]);

            // 计算当前平铺块在原始 PDF 中的起始坐标
            $sourceX = $col * $targetPageWidth;
            $sourceY = $row * $targetPageHeight;

            // 使用 useTemplate 将原始 PDF 的特定区域放置到当前新页面上
            // 参数说明: useTemplate(templateId, x, y, width, height, adjustX, adjustY, adjustWidth, adjustHeight)
            // x, y, width, height: 目标页面上的位置和尺寸 (通常是 0, 0, targetPageWidth, targetPageHeight)
            // adjustX, adjustY, adjustWidth, adjustHeight: 原始模板中要截取的区域
            // FPDI 的 useTemplate 方法的参数签名是 useTemplate($tplId, $x = 0, $y = 0, $width = 0, $height = 0, $adjustCurrentPageSize = false)
            // 截取特定区域需要通过计算 x, y, width, height 来实现，FPDI 会自动裁剪超出部分。
            // 更精确的裁剪通常需要将模板放置后，再通过 SetXY 和 Write 等方式控制内容显示。
            // 对于平铺，我们直接将模板放置到新页面，超出新页面的部分会被自动裁剪。
            // 关键在于计算原始模板的起始点，并将其放置到新页面的 (0,0) 位置。
            // 原始模板内容在目标页面上的实际偏移量是 -sourceX 和 -sourceY
            $pdf->useTemplate(
                $templateId,
                -$sourceX, // 模板在目标页面上的 X 偏移量
                -$sourceY, // 模板在目标页面上的 Y 偏移量
                $originalWidth, // 模板在目标页面上的宽度 (保持原始比例，但会被目标页面裁剪)
                $originalHeight // 模板在目标页面上的高度
            );

            // 可选: 在每个平铺页面上添加标记或裁剪线，方便后期拼接
            // $pdf->SetFont('Arial', 'B', 8);
            // $pdf->Text(5, 5, "Page " . ($row * $numCols + $col + 1) . " of " . ($numRows * $numCols));
        }
    }

    // 输出 PDF
    $pdf->Output('F', $outputPdfPath);
    echo "PDF 分割完成，输出到: {$outputPdfPath}\n";
}

// 示例用法
try {
    $sourcePdf = 'path/to/your/large_pattern.pdf'; // 替换为你的大型 PDF 文件路径
    $outputPdf = 'output_tiled_pattern.pdf';

    // Letter 纸张尺寸 (8.5 x 11 英寸转换为毫米)
    $letterWidthMM = 215.9;
    $letterHeightMM = 279.4;

    splitLargePdfForTiling($sourcePdf, $outputPdf, $letterWidthMM, $letterHeightMM);

} catch (Exception $e) {
    echo '发生错误: ' . $e->getMessage();
}

?>

代码解释：

1. setSourceFile($sourcePdfPath): 导入原始的大型 PDF 文件。
2. importPage(1): 导入原始 PDF 的第一页作为模板。如果原始 PDF 有多页，你需要根据实际情况选择导入哪一页。
3. getTemplateSize($templateId): 获取导入模板的原始尺寸，这对于后续的计算至关重要。
4. $numCols 和 $numRows 计算: 根据原始页面尺寸和目标页面尺寸，计算出需要分割的列数和行数。ceil() 函数确保即使有部分内容超出目标页面，也会生成一个新的页面来包含它。
5. AddPage('P', [$targetPageWidth, $targetPageHeight]): 为每个平铺块创建一个新的 PDF 页面。'P' 表示纵向，[$targetPageWidth, $targetPageHeight] 指定了页面的精确尺寸（单位为毫米）。
6. $sourceX 和 $sourceY 计算: 这两个变量是关键。它们表示当前要绘制的“小块”在原始大页面中的左上角坐标。例如，第一行第一列的 $sourceX 和 $sourceY 都是 0；第一行第二列的 $sourceX 是 $targetPageWidth，$sourceY 仍然是 0。
7. useTemplate($templateId, -$sourceX, -$sourceY, $originalWidth, $originalHeight): 这是 FPDI 实现裁剪和放置的核心。
   • $templateId: 要使用的模板 ID。
   • -$sourceX, -$sourceY: 这是精髓所在。它将原始模板的左上角相对于新页面的左上角进行负向偏移。例如，当处理第一行第二列时，$sourceX 是 $targetPageWidth。将模板的 X 坐标设置为 -$targetPageWidth，意味着原始模板的 $targetPageWidth 处的内容将显示在新页面的 X 轴起始位置（0 处）。这样，就实现了“裁剪”原始大页面的特定区域并将其放置到新页面的效果。
   • $originalWidth, $originalHeight: 指定模板在目标页面上的渲染尺寸。虽然这里传入的是原始尺寸，但由于模板内容会超出目标页面的边界，FPDI 会自动裁剪掉超出部分，从而实现我们想要的平铺效果。

注意事项与最佳实践

1. 单位一致性: FPDF 和 FPDI 默认使用毫米（mm）作为单位。在进行尺寸计算时，请确保所有尺寸都使用相同的单位，避免混淆。如果原始 PDF 的尺寸单位不是毫米，需要进行转换。
2. 边缘处理: 在拼接打印出的页面时，通常会遇到边缘对齐问题。你可以在代码中增加逻辑，在每个子页面上绘制裁剪标记（如虚线或角线），或者在计算 targetPageWidth/targetPageHeight 时预留一定的重叠区域或出血位，方便后期裁剪和拼接。
3. 性能考量: 对于非常巨大的 PDF 文件（例如数百兆甚至数 GB），虽然 FPDI 比图像转换更高效，但仍可能消耗较多内存。确保你的 PHP 内存限制 (memory_limit) 足够。
4. 页面方向: 示例代码假设目标页面是纵向（Portrait）。如果你的目标是横向（Landscape）页面，请在 AddPage 方法中将 'P' 改为 'L'。
5. 错误处理: 在实际应用中，务必添加健壮的错误处理机制，例如检查源文件是否存在、是否可读等。
6. FPDI 版本: 确保使用的 FPDI 版本与 FPDF 兼容，并支持所需的特性。

总结

通过使用 PHP 的 FPDI 库，我们可以优雅地解决大型 PDF 文档的平铺打印问题，避免了传统图像转换方法的诸多弊端。这种方法直接操作 PDF 内容，保证了输出质量，并且在性能上通常优于基于图像的处理方案。掌握 FPDI 的页面导入和模板使用技巧，将使你在 PHP 中处理 PDF 文档时拥有更大的灵活性和控制力。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~