Cấu hình NextPDF Gotenberg

Tổng quan nhanh

Cấu hình gồm hai phần: value object bất biến GotenbergConfig, dùng để mô tả dịch vụ cùng các giới hạn của dịch vụ; và hàm khởi tạo GotenbergBridge, nhận các collaborator PHP Standard Recommendation (PSR) cho Hypertext Transfer Protocol (HTTP). Bạn cung cấp cả hai thông qua constructor injection tường minh. Gói này không có trạng thái toàn cục, không đọc biến môi trường nào và không định nghĩa endpoint mặc định ngầm nào.

Đối tượng cấu hình

GotenbergConfig là một value object final readonly. Tạo trực tiếp bằng các đối số đặt tên, hoặc dựng từ một mảng kết hợp với GotenbergConfig::fromArray().

Các trường

Trường	Kiểu	Mặc định	Hiệu ứng
apiUrl	string	''	Uniform Resource Locator (URL) cơ sở cho dịch vụ Gotenberg. Bắt buộc: giá trị rỗng làm cấu hình không hợp lệ và khiến mọi lần chuyển đổi thất bại ngay lập tức. Phải dùng Hypertext Transfer Protocol Secure (HTTPS).
timeout	int	30	Thời gian chờ cứng cho transport, tính bằng giây. Transport cURL-pinned áp dụng giá trị này khi được chọn.
maxFileSize	int	52_428_800	Kích thước đầu vào tối đa tính bằng byte (50 MiB). Các đầu vào lớn hơn mức này sẽ bị từ chối trước khi có bất kỳ yêu cầu nào.
apiKey	string	''	Bearer token. Khi có giá trị, nó được gửi dưới dạng header Authorization: Bearer <token>. Trường này được đánh dấu #[\SensitiveParameter], nên được che trong stack trace.
pinnedPublicKeys	list<string>	[]	Các pin Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) chính ở dạng sha256/<base64>. Để rỗng sẽ tắt pinning.
backupPublicKeys	list<string>	[]	Các pin TLS SPKI dự phòng, được giữ tách biệt để có thể xác thực việc luân chuyển một cách độc lập.

Khởi tạo trực tiếp

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

Khởi tạo từ một mảng

fromArray() chấp nhận khóa kiểu snake_case và bỏ qua các giá trị sai định dạng thay vì ném ngoại lệ. api_url không phải chuỗi sẽ trở thành ''. timeout không phải int sẽ quay về 30. max_file_size không phải int sẽ quay về giá trị mặc định 50 MiB. Danh sách pin không phải mảng sẽ trở thành []. Các mục không phải chuỗi bên trong những mảng pin sẽ bị loại bỏ.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Cách phân tích khoan dung này là chủ đích. Bạn có thể truyền trực tiếp một mảng cấu hình của framework mà không cần lớp xác thực trước, nhưng vẫn nhận được một đối tượng có kiểu rõ ràng. Nó không kiểm tra xem URL có truy cập được hay các pin có đúng hay không. Bridge thực hiện các kiểm tra đó tại thời điểm chuyển đổi.

Tính hợp lệ

isValid() chỉ trả về true khi apiUrl là một chuỗi không rỗng. Nó không thực hiện kiểm tra mạng hay scheme nào. Chính sách bảo mật xử lý HTTPS và sàng lọc địa chỉ riêng tư tại thời điểm chuyển đổi. Nếu cấu hình không hợp lệ, convertFile() và convertString() sẽ ném ra một GotenbergConvertException với thông báo Invalid Gotenberg configuration: apiUrl is empty. Cấu hình không hợp lệ cũng khiến isAvailable() trả về false mà không thực hiện lệnh gọi mạng nào.

Hàm khởi tạo bridge

GotenbergBridge nhận cấu hình cùng với các collaborator PSR:

Đối số	Kiểu	Bắt buộc	Hiệu ứng
config	GotenbergConfig	có	Mô tả dịch vụ và các giới hạn đã nêu ở trên.
httpClient	Psr\Http\Client\ClientInterface	có	Client PSR-18 dùng cho health probe và transport dự phòng.
requestFactory	Psr\Http\Message\RequestFactoryInterface	có	Dựng request PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	có	Dựng luồng phần thân của request.
logger	Psr\Log\LoggerInterface|null	không (mặc định null)	Khi được cung cấp, ghi một mục log ở mức debug cho mỗi yêu cầu chuyển đổi.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	không	Mặc định dùng chính sách bảo mật Hypertext Markup Language (HTML) của core. Áp dụng ở lớp phân tích và bổ sung cho chính sách ở lớp transport.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	không (mặc định null)	Bắt buộc để kích hoạt transport cURL-pinned. Nếu không có nó, bridge luôn dùng client PSR-18 đã được inject.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

Lựa chọn transport

Bridge hỗ trợ hai transport và chọn một transport cho mỗi yêu cầu chuyển đổi:

• Transport cURL-pinned — được dùng khi một responseFactory đã được inject và có nội dung để pin (URL phân giải ra một hoặc nhiều địa chỉ Internet Protocol (IP), hoặc các pin SPKI đã được cấu hình). Transport này ràng buộc tập địa chỉ đã phân giải bằng CURLOPT_RESOLVE. Nó thực thi SPKI pinning bằng CURLOPT_PINNEDPUBLICKEY khi có pin. Nó xác minh peer và host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Nó áp dụng thời gian chờ đã cấu hình và tắt việc theo dõi chuyển hướng (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Client PSR-18 đã inject — được dùng trong mọi trường hợp khác, kể cả khi URL của application programming interface (API) là một IP công khai dạng thuần (không có Domain Name System (DNS) để pin) và không có pin SPKI nào được cấu hình, hoặc khi không có responseFactory nào được cung cấp.

Để có kết nối chống DNS rebinding và TLS pinning, hãy inject một responseFactory và cấu hình các pin. Health probe luôn dùng client PSR-18 đã inject, bất kể transport được chọn là gì.

Pinning khóa công khai TLS

Pinning dùng mô hình dấu vân tay SPKI theo Secure Hash Algorithm 256-bit (SHA-256). Mỗi pin là một chuỗi có dạng sha256/<base64-encoded-spki-hash>. Transport cũng chấp nhận dạng sha256//<base64> kiểu cURL gốc và chuyển dạng một dấu gạch chéo sang dạng đó. Bất kỳ tiền tố nào khác đều làm phát sinh một InvalidSpkiPinException.

allPublicKeyPins() trả về hợp đã loại trùng của pinnedPublicKeys và backupPublicKeys. Lớp TLS chấp nhận một chứng chỉ có SPKI hash khớp với bất kỳ thành viên nào trong tập kết hợp đó. Trong vận hành, hãy cấu hình ít nhất một pin dự phòng để việc luân chuyển chứng chỉ hoặc khóa theo kế hoạch không làm bridge bị khóa khỏi dịch vụ trong lúc khóa mới đang lan truyền. Giữ danh sách dự phòng tách biệt khỏi danh sách chính cho phép bạn xác thực và luân chuyển pin dự phòng độc lập với pin đang hoạt động. Xem /integrations/gotenberg/security-and-operations/ để biết quy trình luân chuyển.

Tùy chọn chuyển đổi theo từng yêu cầu

Kiểu payload multipart (GotenbergConvertPayload) mang theo tệp cùng hai tùy chọn chuyển đổi không bắt buộc của Gotenberg:

• landscape (bool, mặc định false) — được gửi dưới dạng trường form landscape với "true" hoặc "false".
• nativePageRanges (string, mặc định '') — chỉ được gửi dưới dạng trường form nativePageRanges khi không rỗng; chấp nhận cú pháp khoảng trang của Gotenberg, chẳng hạn như 1-3 hoặc 1,3,5-9.

Các điểm vào công khai convertFile() và convertString() dựng payload với giá trị mặc định cho cả hai trường. Các trường này là một phần của contract payload, và bộ kiểm thử có kiểm tra chúng. Hãy phơi bày chúng từ lớp tích hợp của bạn nếu bạn cần đầu ra nằm ngang hoặc cần chọn trang.

Xem thêm

• /integrations/gotenberg/install/ — cài đặt và baseline của Gotenberg.
• /integrations/gotenberg/quickstart/ — ví dụ đầu cuối có thể chạy được.
• /integrations/gotenberg/production-usage/ — nguồn cấu hình, secret, thời gian chờ, thử lại.
• /integrations/gotenberg/security-and-operations/ — mô hình bảo mật đầy đủ và quy trình luân chuyển pin.
• /integrations/gotenberg/troubleshooting/ — ý nghĩa của các ngoại lệ liên quan đến cấu hình.