Cấu hình NextPDF cho CodeIgniter 4

Tổng quan nhanh

NextPDF lưu cấu hình trong NextPDF\CodeIgniter\Config\NextPdf, một lớp con của BaseConfig trong CodeIgniter. Bạn có thể ghi đè giá trị bằng cách mở rộng lớp này trong app/Config/ hoặc đặt các khóa .env với tiền tố nextpdf.. Các giá trị mặc định hoạt động mà không cần cấu hình thêm.

Tổng quan về khái niệm

NextPdf là một BaseConfig có khai báo kiểu. Lớp này được thiết kế có chủ đích là không phải final. Trong CodeIgniter, cấu hình của ứng dụng mở rộng lớp của gói để ứng dụng của bạn có thể ghi đè các giá trị mặc định. Khi CodeIgniter khởi tạo cấu hình, BaseConfig sẽ phân giải các giá trị ghi đè từ môi trường cho mọi thuộc tính công khai, bao gồm cả các khóa mảng lồng nhau.

Đường dẫn phông chữ và bộ đệm mặc định dùng hằng số WRITEPATH của CodeIgniter: WRITEPATH . 'fonts' và WRITEPATH . 'cache/nextpdf'.

Các khóa cấu hình

Mỗi khóa dưới đây là một thuộc tính công khai của NextPdf. Các giá trị mặc định đã được xác minh dựa trên mã nguồn của gói.

Giá trị mặc định của trang và tài liệu

Khóa	Kiểu	Mặc định	Mô tả
`pageFormat`	`string`	`A4`	Định dạng trang.
`orientation`	`string`	`P`	`P` cho khổ dọc hoặc `L` cho khổ ngang.
`unit`	`string`	`mm`	Đơn vị đo lường.
`defaults.creator`	`string`	`NextPDF`	Siêu dữ liệu creator của Portable Document Format (PDF).
`defaults.author`	`string`	`''`	Siêu dữ liệu tác giả; bỏ qua khi để trống.
`defaults.language`	`string`	`en`	Thẻ ngôn ngữ của tài liệu.
`defaults.margin_top`	`float`	`10.0`	Lề trên.
`defaults.margin_right`	`float`	`10.0`	Lề phải.
`defaults.margin_bottom`	`float`	`10.0`	Lề dưới.
`defaults.margin_left`	`float`	`10.0`	Lề trái.
`defaults.font_family`	`string`	`dejavusans`	Họ phông chữ mặc định.
`defaults.font_size`	`float`	`12.0`	Cỡ phông chữ mặc định.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, nếu được đặt.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, nếu được đặt.

Gói áp dụng defaults.creator và defaults.language cho mọi tài liệu. Gói chỉ áp dụng defaults.author khi giá trị không trống.

Đường dẫn và bộ đệm

Khóa	Kiểu	Mặc định	Mô tả
`fontsPath`	`string`	`WRITEPATH/fonts`	Thư mục tệp phông chữ.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Thư mục bộ đệm.
`preloadFonts`	`list<string>`	`[]`	Các đường dẫn phông chữ tuyệt đối được làm nóng khi khởi động.
`imageCacheMb`	`int`	`50`	Ngân sách bộ đệm hình ảnh theo cơ chế ít được dùng gần đây nhất (LRU), tính bằng megabyte (MB).
`fontCacheLocking`	`bool`	`true`	Khóa bộ đệm phông chữ sau khi làm nóng.

Trình đăng ký phông chữ từ chối mọi fontsPath có chứa stream wrapper (://) hoặc byte null, và phát sinh lỗi thời gian chạy. Xem /integrations/codeigniter/security-and-operations/.

Lưu trữ và màu sắc (NextPDF Pro)

Khóa	Kiểu	Mặc định	Mô tả
`pdfa`	`string\|null`	`null`	Phiên bản PDF/A: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Đường dẫn hồ sơ International Color Consortium (ICC) cho đỏ, lục và lam (RGB).
`iccProfile.cmyk`	`string\|null`	`null`	Đường dẫn hồ sơ ICC cho lục lam, đỏ tươi, vàng và đen (CMYK).

pdfa chỉ có hiệu lực khi NextPDF Pro được cài đặt và khả năng lưu trữ có sẵn. Khi chỉ dùng core, khóa này bị bỏ qua.

Chữ ký số (NextPDF Pro / Enterprise)

Khóa	Kiểu	Mặc định	Mô tả
`signature.enabled`	`bool`	`false`	Bật dịch vụ ký.
`signature.certificate`	`string\|null`	`null`	Đường dẫn tệp chứng chỉ.
`signature.private_key`	`string\|null`	`null`	Đường dẫn tệp khóa riêng tư.
`signature.password`	`string`	`''`	Mật khẩu khóa riêng tư.
`signature.extra_certs`	`list<string>`	`[]`	Các đường dẫn chứng chỉ chuỗi bổ sung.
`signature.level`	`string`	`B-B`	Định danh cấp độ chữ ký.

Services::pdfSigner() trả về null trừ khi signature.enabled là true và signature.certificate không trống. Cấp độ mặc định là B-B. NextPDF Pro cung cấp chữ ký cơ sở B-B. Các cấp độ xác thực dài hạn là khả năng riêng của Enterprise và được ghi lại trong tài liệu tham khảo Premium, không phải ở đây.

PDF Advanced Electronic Signatures (PAdES) B-T được tạo bởi engine Core. Bản tích hợp CodeIgniter tự thân không thêm B-T, và Pro chỉ cung cấp chữ ký cơ sở B-B. Tài liệu này sẽ được cập nhật nếu và khi nào Pro B-T ra mắt.

Cơ quan cấp dấu thời gian

Khóa	Kiểu	Mặc định	Mô tả
`tsa.url`	`string\|null`	`null`	URL điểm cuối của Cơ quan cấp dấu thời gian (TSA).
`tsa.username`	`string`	`''`	Tên người dùng xác thực cơ bản của TSA.
`tsa.password`	`string`	`''`	Mật khẩu xác thực cơ bản của TSA.
`tsa.cert`	`string\|null`	`null`	Đường dẫn chứng chỉ máy khách.
`tsa.key`	`string\|null`	`null`	Đường dẫn khóa máy khách.
`tsa.timeout`	`int`	`30`	Thời gian chờ yêu cầu, tính bằng giây.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Các khóa công khai TSA đã được ghim.
`tsa.warn_on_key_rotation`	`bool`	`true`	Cảnh báo khi xoay vòng khóa TSA.
`tsa.allow_insecure_http`	`bool`	`false`	Cho phép HTTP văn bản thuần đến TSA.

Services::tsaClient() trả về null khi tsa.url là null hoặc là chuỗi rỗng. Khi bạn chọn một cấp độ chữ ký cần dấu thời gian, bộ ký sẽ tự động đính kèm máy khách TSA.

Bộ đệm OCSP

Khóa	Kiểu	Mặc định	Mô tả
`ocspCache.enabled`	`bool`	`true`	Bật bộ đệm phản hồi Online Certificate Status Protocol (OCSP).
`ocspCache.ttl`	`int`	`86400`	Thời gian tồn tại (TTL) của bộ đệm, tính bằng giây.
`ocspCache.directory`	`string\|null`	`null`	Thư mục bộ đệm; dùng mặc định của engine khi để là null.

Bộ kết xuất HTML Chrome (NextPDF Artisan)

Khóa	Kiểu	Mặc định	Mô tả
`artisan.chrome_binary`	`string\|null`	`null`	Đường dẫn tệp nhị phân Chrome/Chromium.
`artisan.render_timeout`	`int`	`30`	Thời gian chờ kết xuất, tính bằng giây.
`artisan.default_css`	`string`	`''`	Bảng định kiểu mặc định.
`artisan.no_sandbox`	`bool`	`false`	Truyền `--no-sandbox` cho Chrome.
`artisan.max_html_size`	`int`	`5000000`	Kích thước HTML đầu vào tối đa, tính bằng byte.

Bộ kết xuất Chrome chỉ được cấu hình cho tài liệu khi artisan.chrome_binary được đặt và nextpdf/artisan được cài đặt.

Ghi đè bằng `.env`

BaseConfig phân giải các giá trị ghi đè từ môi trường theo từng thuộc tính. Khóa tra cứu là tên lớp ngắn viết thường, nextpdf, theo sau là đường dẫn thuộc tính. Dùng dấu chấm để chỉ định các khóa mảng lồng nhau. Cả dạng dùng dấu chấm lẫn dạng dùng gạch dưới đều được chấp nhận.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Tiền tố là tên lớp ngắn viết thường. Nó vẫn là nextpdf ngay cả khi lớp được viết là NextPdf. Bạn cũng có thể dùng dạng đầy đủ (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Ghi đè bằng cách mở rộng lớp

Để có cấu hình có khai báo kiểu và được quản lý phiên bản, hãy mở rộng lớp của gói trong app/Config/. CodeIgniter tải lớp của ứng dụng thay cho mặc định của gói. Tệp này khai báo một lớp và không gây tác dụng phụ. Điều này giúp tệp phù hợp với kỳ vọng của PSR-1 rằng một tệp hoặc khai báo ký hiệu, hoặc chạy logic có tác dụng phụ, nhưng không làm cả hai việc (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

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

Ghi đè một khóa lồng nhau bằng .env chỉ thay đổi khóa đó; phần còn lại của mảng vẫn giữ giá trị mặc định.
.env lưu giá trị dưới dạng chuỗi. CodeIgniter chuyển đổi true/false và các chuỗi số. Hãy đặt trong dấu nháy những giá trị cần giữ nguyên là chuỗi ký tự.
Mở rộng lớp bằng một mảng defaults chỉ có một phần sẽ thay thế toàn bộ mảng. Hãy bao gồm mọi khóa, như minh họa ở trên.

Ghi chú bảo mật

Đừng đưa đường dẫn chứng chỉ và khóa vào hệ thống quản lý mã nguồn. Hãy cung cấp chúng qua .env hoặc một trình quản lý bí mật. tsa.allow_insecure_http phải được giữ ở mức false trong môi trường production. Xem /integrations/codeigniter/security-and-operations/.

Tuân thủ

Tệp mở rộng cấu hình của ứng dụng khai báo một lớp và không có tác dụng phụ (PSR-1 §x1.x1.p3).

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

NextPDF core là Apache-2.0. Các khóa signature.* và pdfa chỉ có hiệu lực khi NextPDF Pro hoặc Enterprise được cài đặt. Gói CodeIgniter cung cấp các phương thức dịch vụ tương ứng. Các phương thức đó trả về null cho đến khi bạn cài đặt gói Premium tương ứng. Xem </get-license/?intent=codeigniter-signing>.

Xem thêm

/integrations/codeigniter/install/ — cài đặt gói.
/integrations/codeigniter/quickstart/ — PDF đầu tiên.
/integrations/codeigniter/production-usage/ — các controller và queue job được kết nối qua DI.
/integrations/codeigniter/security-and-operations/ — gia cố cấu hình ký và đường dẫn.