跳轉到

設定

NextPDF 使用不可變的設定值物件（Configuration）控制文件生成行為。所有選項均有合理的預設值，開發者只需覆寫需要調整的項目。


PHP Compatibility

This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.

設定物件在文件建立時傳入，之後不可修改——這確保同一份設定可安全地在多個並行文件中重複使用。

建立設定

use NextPDF\Core\Configuration;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Margin;

$config = Configuration::create(
    pageSize: PageSize::A4,
    margin: Margin::uniform(20.0),
    title: 'Annual Report 2026',
    author: 'Acme Corp',
);

頁面設定

選項 型別 預設值 說明
pageSize PageSize PageSize::A4 頁面尺寸（ISO 216 或自訂）
orientation Orientation Orientation::Portrait 直向 / 橫向
margin Margin Margin::uniform(15.0) 頁面邊距（mm）
unit Unit Unit::Millimeter 座標單位

文件中繼資料

選項 型別 預設值 說明
title non-empty-string\|null null PDF 標題
author non-empty-string\|null null 作者
subject non-empty-string\|null null 主題
keywords list<string> [] 關鍵字
creator non-empty-string 'NextPDF' 建立工具
producer non-empty-string 'NextPDF Core' 轉換工具

安全性設定

use NextPDF\Security\EncryptionConfig;
use NextPDF\Security\Permission;

$config = Configuration::create(
    encryption: EncryptionConfig::aes256(
        userPassword: 'user-pass',
        ownerPassword: 'owner-pass',
        permissions: Permission::PRINT | Permission::COPY,
    ),
);

PDF/A 與 PDF/UA 合規模式

選項 型別 預設值 說明
conformance Conformance\|null null PDF_A4、PDF_UA2 等
taggedPdf bool false 啟用 Tagged PDF 結構

獨立模式 vs 工廠模式

// 獨立模式（每次呼叫完整初始化）
$document = Document::createStandalone($config);

// 工廠模式（共享 Process 資源）
$process = Process::create();
$document = $process->factory()->create($config);

獨立模式適合 CLI 腳本與無狀態 Workers；工廠模式適合需要高效重用字型快取與影像快取的長時間執行服務。

效能調校選項

選項 型別 預設值 說明
enableSpectrum bool false 啟用 Rust FFI 加速器
fontCacheDir non-empty-string\|null 系統暫存 字型快取目錄
imageCacheSize positive-int 64 影像快取上限（MB）

參見