PDF 合併¶
PdfMerger 提供生產等級的 PDF 合併能力，支援頁面範圍選取、書籤保留、表單欄位合併，以及加密文件的安全處理。單次合併操作最多支援 100 個來源檔案，總輸入大小上限為 200 MB。
基本用法¶
use NextPDF\Core\PdfMerger;
use NextPDF\Core\PageRange;
$merger = PdfMerger::create();
// 加入完整文件
$merger->add(source: '/path/to/document1.pdf');
$merger->add(source: '/path/to/document2.pdf');
// 合併並輸出
$pdfBytes = $merger->merge();
頁面範圍選取¶
使用 PageRange 指定要合併的特定頁面：
use NextPDF\Core\PageRange;
// 第 1 至 5 頁
$merger->add(
source: '/path/to/report.pdf',
pageRange: PageRange::fromTo(first: 1, last: 5),
);
// 僅第 3 頁
$merger->add(
source: '/path/to/cover.pdf',
pageRange: PageRange::single(page: 3),
);
// 第 2 頁到最後一頁
$merger->add(
source: '/path/to/appendix.pdf',
pageRange: PageRange::from(first: 2),
);
// 非連續頁面
$merger->add(
source: '/path/to/source.pdf',
pageRange: PageRange::pages(pages: [1, 3, 7, 11]),
);
來源類型¶
// 從檔案路徑
$merger->add(source: '/path/to/file.pdf');
// 從 PHP resource（檔案串流）
$stream = fopen('/path/to/file.pdf', 'r');
$merger->addStream(stream: $stream);
// 從位元組字串（記憶體中的 PDF）
$merger->addBytes(bytes: $pdfBytes);
加密文件¶
// 提供使用者密碼以合併受保護的 PDF
$merger->add(
source: '/path/to/protected.pdf',
userPassword: 'user-password',
);
資源限制¶
| 限制項目 | 上限 | 超限行為 |
|---|---|---|
| 來源檔案數量 | 100 個 | 拋出 MergeLimitException |
| 總輸入大小 | 200 MB | 拋出 MergeLimitException |
| 單一頁面數 | 10,000 頁 | 拋出 MergeLimitException |
use NextPDF\Core\Exception\MergeLimitException;
try {
$pdfBytes = $merger->merge();
} catch (MergeLimitException $e) {
// 處理超限狀況
logger()->error('PDF merge limit exceeded', ['reason' => $e->getMessage()]);
}
書籤與中繼資料¶
// 控制書籤的合併行為
$merger->setBookmarkHandling(
mode: BookmarkMode::Merge, // Merge | Flatten | Discard
);
// 設定合併後文件的中繼資料
$merger->setOutputMetadata(
title: 'Merged Document',
author: 'Acme Corp',
);
輸出選項¶
// 輸出為位元組字串
$bytes = $merger->merge();
// 直接寫入檔案（串流模式，避免記憶體峰值）
$merger->mergeToFile(path: '/output/merged.pdf');
// 取得 PHP resource 串流
$stream = $merger->mergeToStream();