Laravel 設定

發布設定檔後，可在 config/tcpdf-next.php 中自訂所有預設行為。

php artisan vendor:publish --tag=tcpdf-next-config

以下是完整的設定區段與對應的環境變數。

頁面預設值

'page' => [
    'format'      => env('TCPDF_PAGE_FORMAT', 'A4'),
    'orientation'  => env('TCPDF_PAGE_ORIENTATION', 'P'),  // P=直式, L=橫式
    'margin_left'  => env('TCPDF_MARGIN_LEFT', 15),
    'margin_top'   => env('TCPDF_MARGIN_TOP', 27),
    'margin_right' => env('TCPDF_MARGIN_RIGHT', 15),
    'margin_bottom' => env('TCPDF_MARGIN_BOTTOM', 25),
    'auto_page_break' => true,
],

環境變數	預設值	說明
TCPDF_PAGE_FORMAT	A4	頁面尺寸（A4、Letter、A5 等）
TCPDF_PAGE_ORIENTATION	P	直式（P）或橫式（L）
TCPDF_MARGIN_LEFT	15	左邊距（mm）
TCPDF_MARGIN_TOP	27	上邊距（mm）
TCPDF_MARGIN_RIGHT	15	右邊距（mm）
TCPDF_MARGIN_BOTTOM	25	下邊距（mm）

字型

'font' => [
    'default_family' => env('TCPDF_FONT_FAMILY', 'Helvetica'),
    'default_size'   => env('TCPDF_FONT_SIZE', 11),
    'directory'      => env('TCPDF_FONT_DIR', resource_path('fonts/tcpdf')),
    'cache_directory' => env('TCPDF_FONT_CACHE_DIR', storage_path('framework/cache/tcpdf-fonts')),
    'subsetting'     => true,
],

環境變數	預設值	說明
TCPDF_FONT_FAMILY	Helvetica	預設字型家族
TCPDF_FONT_SIZE	11	預設字型大小（pt）
TCPDF_FONT_DIR	resource_path(...)	自訂字型目錄
TCPDF_FONT_CACHE_DIR	storage_path(...)	字型快取目錄

啟用 subsetting 可大幅減小嵌入 CJK 字型時的檔案大小。

加密

'encryption' => [
    'enabled'     => env('TCPDF_ENCRYPTION_ENABLED', false),
    'algorithm'   => env('TCPDF_ENCRYPTION_ALGO', 'AES-256'),   // AES-256 或 AES-128
    'user_password'  => env('TCPDF_USER_PASSWORD', ''),
    'owner_password' => env('TCPDF_OWNER_PASSWORD', ''),
    'permissions' => [
        'print'          => true,
        'copy'           => false,
        'modify'         => false,
        'annotate'       => true,
        'fill_forms'     => true,
        'extract'        => false,
        'assemble'       => false,
        'print_highres'  => true,
    ],
],

環境變數	預設值	說明
TCPDF_ENCRYPTION_ENABLED	false	是否啟用加密
TCPDF_ENCRYPTION_ALGO	AES-256	加密演算法
TCPDF_USER_PASSWORD	''	開啟文件密碼（空字串表示無需密碼可開啟）
TCPDF_OWNER_PASSWORD	''	擁有者密碼（控制權限變更）

安全提醒

請勿將密碼硬編碼在設定檔中。務必使用環境變數或 Laravel 的加密儲存。

數位簽章

'signature' => [
    'enabled'         => env('TCPDF_SIGNATURE_ENABLED', false),
    'certificate_path' => env('TCPDF_CERT_PATH', ''),
    'private_key_path' => env('TCPDF_KEY_PATH', ''),
    'password'        => env('TCPDF_CERT_PASSWORD', ''),
    'tsa_url'         => env('TCPDF_TSA_URL', ''),
    'pades_level'     => env('TCPDF_PADES_LEVEL', 'B-LTA'),
],

環境變數	預設值	說明
TCPDF_SIGNATURE_ENABLED	false	是否啟用數位簽章
TCPDF_CERT_PATH	''	PKCS#12 或 PEM 憑證路徑
TCPDF_KEY_PATH	''	私鑰路徑
TCPDF_CERT_PASSWORD	''	憑證密碼
TCPDF_TSA_URL	''	時間戳記伺服器（TSA）URL
TCPDF_PADES_LEVEL	B-LTA	PAdES 簽章等級（B-B、B-T、B-LT、B-LTA）

佇列

'queue' => [
    'connection' => env('TCPDF_QUEUE_CONNECTION', 'redis'),
    'name'       => env('TCPDF_QUEUE_NAME', 'pdf-generation'),
    'tries'      => (int) env('TCPDF_QUEUE_TRIES', 3),
    'timeout'    => (int) env('TCPDF_QUEUE_TIMEOUT', 120),
    'backoff'    => [10, 30, 60],
],

環境變數	預設值	說明
TCPDF_QUEUE_CONNECTION	redis	佇列連線驅動
TCPDF_QUEUE_NAME	pdf-generation	佇列名稱
TCPDF_QUEUE_TRIES	3	最大重試次數
TCPDF_QUEUE_TIMEOUT	120	任務逾時（秒）

輸出

'output' => [
    'compression'   => env('TCPDF_COMPRESSION', true),
    'pdf_version'   => env('TCPDF_PDF_VERSION', '2.0'),
    'color_profile' => env('TCPDF_COLOR_PROFILE', 'sRGB'),
    'tagged_pdf'    => env('TCPDF_TAGGED_PDF', false),
],

環境變數	預設值	說明
TCPDF_COMPRESSION	true	啟用 Flate 串流壓縮
TCPDF_PDF_VERSION	2.0	PDF 版本（1.7 或 2.0）
TCPDF_COLOR_PROFILE	sRGB	ICC 色彩設定檔
TCPDF_TAGGED_PDF	false	產生標記式 PDF（無障礙）

環境變數範例

在 .env 中加入常用設定：

# 頁面
TCPDF_PAGE_FORMAT=A4
TCPDF_PAGE_ORIENTATION=P

# 字型
TCPDF_FONT_FAMILY=NotoSansTC
TCPDF_FONT_SIZE=11

# 加密
TCPDF_ENCRYPTION_ENABLED=true
TCPDF_ENCRYPTION_ALGO=AES-256
TCPDF_USER_PASSWORD=
TCPDF_OWNER_PASSWORD="${APP_KEY}"

# 佇列
TCPDF_QUEUE_CONNECTION=redis
TCPDF_QUEUE_NAME=pdf-generation
TCPDF_QUEUE_TRIES=3
TCPDF_QUEUE_TIMEOUT=120

下一步

• 套件總覽 — 安裝與架構概觀
• Pdf 門面 — 透過門面覆寫設定
• 佇列任務 — 佇列相關設定實際應用