Cấu hình gói NextPDF Laravel

Tổng quan nhanh

config/nextpdf.php được publish bằng php artisan vendor:publish --tag=nextpdf-config. Mỗi khóa đều có biến môi trường dự phòng và giá trị mặc định cố định trong mã. Trang này liệt kê từng khóa đúng như cách khóa đó xuất hiện trong config/nextpdf.php của gói.

Cài đặt

php artisan vendor:publish --tag=nextpdf-config

Trong quá trình register(), provider cũng gộp các giá trị mặc định của gói vào khóa config nextpdf. Những khóa chưa được thiết lập khi đó sẽ dùng các giá trị bên dưới, kể cả trước khi bạn publish tệp config.

Tổng quan khái niệm

Hầu hết các biến môi trường chấp nhận tên dạng NEXTPDF_* hoặc tên cũ dạng TCPDF_*. Tiền tố cũ vẫn dùng được trong giai đoạn chuyển tiếp được mô tả trong UPGRADE.md. Dùng NEXTPDF_* cho các triển khai mới. Tệp config phân giải giá trị theo thứ tự ưu tiên này: biến môi trường → giá trị trong tệp đã publish → giá trị mặc định của gói.

Bề mặt API — các khóa cấu hình

Bố cục tài liệu

Khóa	Env (chính)	Mặc định	Hiệu ứng
page_format	NEXTPDF_PAGE_FORMAT	A4	Khổ trang mặc định: A4, A3, A5, Letter, Legal hoặc Tabloid
orientation	NEXTPDF_ORIENTATION	P	Dọc (P) hoặc ngang (L)
unit	NEXTPDF_UNIT	mm	Đơn vị đo: pt, mm, cm hoặc in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadata về người tạo tài liệu; được áp dụng cho PdfDocumentInterface binding
defaults.author	NEXTPDF_AUTHOR	(trống)	Metadata tác giả; chỉ được áp dụng khi không rỗng
defaults.language	NEXTPDF_LANG	en	Ngôn ngữ tài liệu; được áp dụng cho document binding
defaults.margin_top / _right / _bottom / _left	—	10	Lề mặc định
defaults.font_family	—	dejavusans	Họ phông chữ mặc định
defaults.font_size	—	12	Cỡ phông chữ mặc định
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] theo điểm (point), hoặc null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] theo điểm (point), hoặc null

Provider áp dụng defaults.creator, defaults.language, và (khi được thiết lập) defaults.author cho mỗi tài liệu vừa được phân giải. Provider bỏ qua defaults.author khi giá trị rỗng.

Lưu trữ và màu sắc

Khóa	Env (chính)	Mặc định	Hiệu ứng
pdfa	NEXTPDF_PDFA	null	Cấp độ lưu trữ PDF/A: null, 4, 4e, hoặc 4f. Bất kỳ giá trị nào khác null sẽ bật PDF/A trên document binding và yêu cầu nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Thư mục chứa các phông chữ TrueType bổ sung; thiết lập đường dẫn tìm kiếm của font registry
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Thư mục cache cho phông chữ đã phân tích và tệp tạm
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Đường dẫn hồ sơ ICC RGB; bắt buộc cho PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Hồ sơ ICC CMYK tùy chọn cho quy trình in
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Dùng flock cho cache phông chữ để tránh hỏng dữ liệu khi nhiều queue worker ghi đồng thời

Giá trị pdfa khác null yêu cầu gói Premium. Nếu thiếu nextpdf/premium, việc phân giải binding của tài liệu khi pdfa đã được thiết lập sẽ phát sinh lỗi không tìm thấy lớp cho kiểu phiên bản PDF/A. Trang này không mô tả hành vi lưu trữ của Premium. Xem tài liệu Premium.

Bộ nhớ worker (runtime tồn tại lâu)

Khóa	Env (chính)	Mặc định	Hiệu ứng
preload_fonts	—	[]	Các đường dẫn tuyệt đối đến tệp phông chữ được phân tích khi worker khởi động. Font registry bị khóa sau warm start
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Ngân sách cache ảnh theo kiểu ít dùng gần đây nhất (LRU) tính bằng megabyte (MB). 0 tắt cache. Không có giới hạn trên nào được áp dụng ở cấp provider

Ngân sách cache ảnh không có giới hạn trên do provider áp dụng. Hãy dùng giới hạn bộ nhớ của container hoặc php.inimemory_limit để giới hạn nó. Tệp config khuyến nghị mức tối đa thực tế là 256 MB.

Chữ ký số (Premium)

Khóa	Env (chính)	Mặc định	Hiệu ứng
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Khi là false, hoặc khi chứng chỉ rỗng, SignerInterface sẽ phân giải thành null
signature.certificate	NEXTPDF_SIGN_CERT	null	Đường dẫn chứng chỉ ký
signature.private_key	NEXTPDF_SIGN_KEY	null	Đường dẫn khóa riêng tư
signature.password	NEXTPDF_SIGN_PASSWORD	(trống)	Cụm mật khẩu của khóa
signature.extra_certs	—	[]	Các đường dẫn chứng chỉ CA trung gian
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Cấp độ baseline Chữ ký Điện tử Nâng cao cho PDF (PAdES) được truyền cho signer

Gói Core được mô tả ở đây không kèm phần triển khai signer; SignerInterface phân giải thành null cho đến khi nextpdf/premium cung cấp một bản triển khai. Với Premium, level: B-B tạo ra một chữ ký baseline PAdES B-B. Các baseline PAdES cao hơn phụ thuộc vào timestamp authority đã được cấu hình và khả năng Premium; trang này không mô tả các cấp độ đó.

Timestamp authority

Khóa	Env (chính)	Mặc định	Hiệu ứng
tsa.url	NEXTPDF_TSA_URL	null	Endpoint của timestamp authority (TSA). Khi để trống, TsaClient phân giải thành null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(trống)	Thông tin đăng nhập HTTP của TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Chứng chỉ / khóa client cho Bảo mật tầng truyền tải hai chiều (mTLS) tới TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Thời gian chờ HTTP tính bằng giây cho client PSR-18
tsa.pinned_public_keys	—	[]	Các pin SubjectPublicKeyInfo (SPKI) SHA-256 dạng Base64 (RFC 7469). Để trống sẽ tắt pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Phát ra cảnh báo khi TSA xuất trình một SPKI không được pin
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Cho phép HTTP văn bản thuần tới TSA. Hãy giữ là false trong môi trường production

Cache phản hồi OCSP

Khóa	Env (chính)	Mặc định	Hiệu ứng
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Cache phản hồi của Giao thức Trạng thái Chứng chỉ Trực tuyến (OCSP) trong khi xác thực
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL của cache tính bằng giây
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Thư mục cache; null giữ cache chỉ trong bộ nhớ

Hàng đợi

Khóa	Env (chính)	Mặc định	Hiệu ứng
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Kết nối hàng đợi; null dùng kết nối mặc định
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Hàng đợi mà GeneratePdfJob được đẩy vào
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Thời gian chờ mỗi công việc tính bằng giây

Bộ kết xuất Chrome CDP (tiện ích mở rộng Artisan)

Khóa	Env (chính)	Mặc định	Hiệu ứng
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	giá trị env hoặc chưa thiết lập	Đường dẫn tới tệp nhị phân Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Thời gian chờ kết xuất tính bằng giây
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(trống)	CSS mặc định được chèn vào HTML đã kết xuất
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Tắt Chrome sandbox
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Kích thước HTML đầu vào tối đa tính bằng byte

Phần artisan chỉ được áp dụng cho document binding khi có lớp browser-factory của Chrome (tiện ích mở rộng nextpdf/artisan). Khi không có lớp đó, phần này bị bỏ qua.

Ví dụ mã — Production

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Trường hợp đặc biệt và những lưu ý

• signature.enabled = true với signature.certificate rỗng vẫn phân giải SignerInterface thành null; cả hai giá trị đều phải được thiết lập.
• tsa.url = null buộc TsaClient thành null, ngay cả khi các khóa tsa.* khác đã được điền giá trị.
• signature.level = null quay về dùng PAdES B-B trên signer.
• image_cache_mb đặt thành null (không phải 0) sẽ quay về dùng giá trị mặc định 50 MB; 0 tắt cache một cách tường minh.
• Các biến môi trường cũ TCPDF_* vẫn đọc được nhưng không còn được khuyến nghị. Hãy chuyển sang NEXTPDF_*.

Hiệu năng

Đọc config dùng truy cập mảng O(1). preload_fonts đánh đổi một lần phân tích O(f) khi worker khởi động để có độ trễ thấp hơn ở yêu cầu đầu tiên. image_cache_mb lớn hơn sẽ giảm việc giải mã ảnh lặp lại, đổi lại là bộ nhớ thường trú trong tiến trình.

Lưu ý bảo mật

tsa.allow_insecure_http làm suy yếu mức độ tin cậy của timestamp và phải luôn ở false trong môi trường production. URL của TSA chỉ nên đến từ cấu hình đáng tin cậy. Nếu bạn để lộ chúng qua bề mặt quản trị, hãy dùng tường lửa egress hoặc chính sách DNS để giảm thiểu rủi ro giả mạo yêu cầu. Xem /integrations/laravel/security-and-operations/.

Tính tuân thủ

Không có tiêu chuẩn quy phạm nào chi phối cấu trúc của tệp cấu hình. Tất cả các khóa đều được kiểm chứng đối chiếu với config/nextpdf.php của gói tại bản sửa đổi được mô tả. Premium chi phối ngữ nghĩa cấp độ chữ ký, vốn nằm ngoài phạm vi của trang Core này.

Bối cảnh thương mại

Phần signature và tsa kích hoạt luồng ký của Premium khi nextpdf/premium được cài đặt. Khả năng Enterprise tùy chọn này không yêu cầu thay đổi mã của gói Core. Xem https://nextpdf.dev/get-license/?intent=laravel-signing.

Xem thêm

• /integrations/laravel/install/ — publish tệp config
• /integrations/laravel/production-usage/ — xem cấu hình được áp dụng trong một controller thực tế
• /integrations/laravel/security-and-operations/ — gia cố thiết lập TSA và hàng đợi
• /integrations/laravel/boot-and-discovery/ — xem mỗi khóa tác động đến binding nào