Tích hợp NextPDF với Gotenberg

Tổng quan nhanh

Trang này hướng dẫn cách kết nối cầu nối với phần còn lại của ứng dụng. Hãy cài đặt, kết nối, rồi đưa tệp Portable Document Format (PDF) đã chuyển đổi vào pipeline xử lý hậu kỳ của NextPDF. Cầu nối chuyển đổi tài liệu Office sang PDF; pipeline xử lý mọi việc sau bước chuyển đổi. Để hiểu thiết kế phía sau cách kết nối này, xem /integrations/gotenberg/boot-and-discovery/.

Cài đặt

composer require nextpdf/gotenberg

Cài đặt gói này cũng sẽ cài nextpdf/core ^3.0 và các contract PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP). Hãy cài client PSR-18 và các factory PSR-17 dưới dạng các gói riêng. Cầu nối chỉ phụ thuộc vào các interface, nên bạn có thể tự chọn thư viện cụ thể. Để xem đầy đủ các bước cài đặt, bao gồm cách chạy dịch vụ Gotenberg qua Hypertext Transfer Protocol Secure (HTTPS), xem /integrations/gotenberg/install/.

Kết nối

Tạo cầu nối bằng một đối tượng cấu hình và các collaborator PSR. Đồng thời, hãy inject một response factory; factory này bật transport có DNS-pinning (Domain Name System) và TLS-pinning (Transport Layer Security):

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Cầu nối yêu cầu HTTPS cho URL đã cấu hình. Nó từ chối http:// thuần trước khi gửi bất kỳ yêu cầu nào. Hãy chạy Gotenberg phía sau TLS termination, rồi trỏ cầu nối đến endpoint HTTPS.

Đăng ký với container

Đăng ký ba mục trong container của ứng dụng: GotenbergConfig được dựng từ nguồn cấu hình của bạn, client PSR-18 cùng các factory PSR-17, và GotenbergBridge, được nối từ các phụ thuộc đó. Gói này không đi kèm binding riêng. Việc đăng ký theo cách riêng của framework thuộc về các gói tích hợp framework chuyên dụng. Xem /integrations/gotenberg/boot-and-discovery/.

Cấu hình

Tất cả trường mô tả dịch vụ và các giới hạn đều nằm trong GotenbergConfig. Chúng bao gồm URL của giao diện lập trình ứng dụng (API), timeout, giới hạn kích thước, bearer token, và các TLS pin. Các tùy chọn theo từng yêu cầu, landscape và nativePageRanges, nằm trên kiểu payload. /integrations/gotenberg/configuration/ ghi tài liệu cho từng trường, kèm kiểu, giá trị mặc định và tác dụng của trường đó.

Đưa tệp PDF đã chuyển đổi vào một pipeline NextPDF

Một luồng end-to-end điển hình:

1. Chuyển đổi tài liệu Office bằng convertFile() hoặc convertString().
2. Lấy $result->pdfData, vốn chứa các byte PDF thô, rồi nạp vào tài liệu NextPDF.
3. Áp dụng xử lý hậu kỳ, chẳng hạn ghép trang, thêm hình mờ, chuyển đổi PDF/A, hoặc chữ ký số.

Bước 3 thuộc về NextPDF, không phải cầu nối. Gói nextpdf/premium cung cấp chức năng ký, các profile PDF/A, và thêm hình mờ. Hãy giữ chuyển đổi và xử lý hậu kỳ thành hai giai đoạn riêng để bạn có thể chẩn đoán từng lỗi một cách độc lập.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Hỗ trợ PDF Advanced Electronic Signatures (PAdES) trong bản Pro chỉ là baseline B-B. Nó không cung cấp B-T, B-LT, hay B-LTA. Việc chuyển đổi tài liệu qua cầu nối này không kéo theo bất kỳ khả năng timestamp hay long-term-validation nào.

Kiểm tra nhanh

Sau khi kết nối, hãy xác nhận phần tích hợp mà không cần chuyển đổi tài liệu thật:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() xác thực URL mà không tạo lưu lượng mạng. Sau đó, nó gửi một yêu cầu HEAD tới <apiUrl>/health. Tiếp theo, hãy chuyển đổi một tài liệu nhỏ đã biết là đúng. Việc này chạy thử trọn vẹn đường dẫn multipart tới <apiUrl>/forms/libreoffice/convert và xác thực phản hồi.

Các điểm vào API công khai

Bề mặt công khai mà phần tích hợp này sử dụng:

• GotenbergConfig — mô tả dịch vụ và các giới hạn, bất biến; fromArray() dựng đối tượng này từ một mảng cấu hình.
• GotenbergBridge::convertFile(string $path) — chuyển đổi một tệp trên ổ đĩa.
• GotenbergBridge::convertString(string $bytes, string $fileName) — chuyển đổi các byte đang nằm trong bộ nhớ.
• GotenbergBridge::isAvailable() — phép thăm dò mức sẵn sàng, không ném ngoại lệ.
• GotenbergConvertResult — mang theo pdfData, sourceFormat, isValid(), và size().
• GotenbergConvertException — kiểu ngoại lệ của lớp chuyển đổi.

Contract đầy đủ nằm trong /integrations/gotenberg/configuration/ và /integrations/gotenberg/troubleshooting/. Nội dung này bao gồm cách chọn transport và danh mục ngoại lệ.

Xem thêm

• /integrations/gotenberg/boot-and-discovery/ — lý do cách kết nối có hình dạng như vậy.
• /integrations/gotenberg/quickstart/ — lần chuyển đổi đầu tiên có hướng dẫn.
• /integrations/gotenberg/production-usage/ — secret, retry, timeout, observability.
• /integrations/gotenberg/install/ — cài đặt gói và dịch vụ Gotenberg.