Cài đặt NextPDF Gotenberg

Tổng quan nhanh

Quá trình cài đặt bridge gồm hai phần: gói PHP cùng các phần phụ thuộc HTTP theo PHP Standard Recommendation (PSR) được cài bằng Composer, và dịch vụ Gotenberg mà gói này gọi đến. Bridge chuyển đổi tệp bằng cách gửi công việc đến dịch vụ đó, nên nó chưa thể chuyển đổi bất cứ thứ gì cho đến khi có một phiên bản Gotenberg có thể truy cập.

Hãy hoàn thành cả hai phần trước khi bạn viết mã chuyển đổi.

Yêu cầu

Yêu cầu	Ràng buộc	Lý do
PHP	>=8.4 <9.0	Do gói khai báo trong composer.json.
NextPDF core	^3.0	Được khai báo là phần phụ thuộc trực tiếp trong composer.json.
PSR-18 HTTP client	^1.0	Bridge gửi yêu cầu thông qua một Psr\Http\Client\ClientInterface được tiêm.
PSR-17 HTTP factories	^1.1	Bridge tạo các yêu cầu và luồng bằng các PSR-17 factories được tiêm.
PSR-3 logger	^3.0 (tùy chọn)	Bạn có thể tiêm một logger để ghi nhật ký gỡ lỗi ở cấp yêu cầu.
Dịch vụ Gotenberg	Có thể truy cập qua HTTPS	Dịch vụ bên ngoài thực hiện chuyển đổi; gói này không làm việc đó.

Bridge không đi kèm sẵn PSR-18 client hay PSR-17 factories. Hãy chọn các triển khai phù hợp với ứng dụng của bạn. Ví dụ, hãy ghép một client dựa trên Guzzle với các PSR-17 factories của nó, hoặc dùng Symfony HTTP client với nyholm/psr7. Bất kỳ triển khai nào tuân thủ các hợp đồng PSR liên quan đều hoạt động được, vì bridge phụ thuộc vào các interface chứ không phải một thư viện cụ thể.

Bước 1 — cài đặt gói

Thêm gói bằng Composer:

composer require nextpdf/gotenberg

Composer giải quyết nextpdf/core ^3.0 cùng các hợp đồng PSR HTTP: psr/http-client, psr/http-factory và psr/log. Nó không cài đặt HTTP client cụ thể nào.

Bước 2 — cài đặt một PSR-18 client và PSR-17 factories

Cài đặt một PSR-18 client và bộ PSR-17 factories tương ứng. Với Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Hoặc với Symfony HTTP client và Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Truyền các triển khai này vào constructor của bridge. Bridge không bao giờ tự tạo HTTP client. Bạn chọn triển khai khi ráp nối bridge. Xem /integrations/gotenberg/configuration/ để biết hình dạng của constructor và /integrations/gotenberg/quickstart/ để xem một ví dụ ráp nối hoàn chỉnh.

Bước 3 — dựng một dịch vụ Gotenberg

Bridge gọi route chuyển đổi LibreOffice của Gotenberg, nên hãy chạy một phiên bản Gotenberg mà bridge có thể truy cập. Dự án upstream phát hành một container image. Để phát triển cục bộ, hãy dùng:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Lệnh này mở Gotenberg trên cổng 3000 qua HTTP thuần. Chỉ dùng nó để phát triển cục bộ. Bridge yêu cầu HTTPS cho URL application programming interface (API) được cấu hình và từ chối http:// thuần trước khi gửi bất kỳ yêu cầu nào. Với bất cứ môi trường nào vượt ngoài thử nghiệm cục bộ, hãy đặt Gotenberg phía sau reverse proxy hoặc service mesh có khả năng kết thúc Transport Layer Security (TLS), rồi trỏ bridge tới endpoint HTTPS. /integrations/gotenberg/security-and-operations/ trình bày hình dạng triển khai cho production, mức độ phơi bày mạng và xác thực.

Image tag được hiển thị ở đây (gotenberg/gotenberg:8) là dòng major của upstream Gotenberg. README và baseline tích hợp của dự án này đều tham chiếu dòng đó. Trong production, hãy ghim vào một patch tag cụ thể thay vì theo dõi một major tag luôn thay đổi. Đồng thời, hãy xác minh các đường dẫn route (/forms/libreoffice/convert, /health) so với phiên bản Gotenberg mà bạn triển khai. Bridge giả định hai đường dẫn đó và không đưa ra giả định nào khác về dịch vụ này.

Bước 4 — kiểm tra việc ráp nối

Đến đây, gói và HTTP client đã được cài đặt, và Gotenberg có thể truy cập qua HTTPS. Trước khi chạy một lần chuyển đổi thực sự, hãy xác nhận bridge có thể truy cập dịch vụ bằng health probe tích hợp sẵn:

<?php

declare(strict_types=1);

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

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

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() kiểm tra URL đã cấu hình trước tiên. Nó trả về false đối với URL rỗng, URL không phải HTTPS, hoặc URL địa chỉ riêng tư mà không gửi lưu lượng mạng. Sau đó, nó gửi một yêu cầu HEAD tới <apiUrl>/health và báo cáo dịch vụ là khả dụng khi trạng thái thấp hơn 500. Nếu xảy ra lỗi mạng, bridge sẽ bắt lỗi và báo cáo dịch vụ không khả dụng thay vì ném ra một exception.

Lưu ý về phiên bản

Tài liệu này mô tả gói ở dòng ^3.0. Dòng đó khớp với yêu cầu trong composer.json và ma trận hỗ trợ trong SECURITY.md, trong đó 3.x được hỗ trợ còn 2.x thì không. Các tham chiếu 0.x trước đó trong các trang skeleton bên trong kho lưu trữ có từ trước dòng 3.0. Ràng buộc trong composer.json thay thế cho chúng.

Xem thêm

• /integrations/gotenberg/overview/ — bridge làm gì và chuyển đổi các định dạng nào.
• /integrations/gotenberg/configuration/ — mọi đối số của constructor và trường cấu hình.
• /integrations/gotenberg/quickstart/ — lần chuyển đổi đầu tiên hoàn chỉnh, chạy được.
• /integrations/gotenberg/security-and-operations/ — cách vận hành phần phụ thuộc Gotenberg một cách an toàn.
• /integrations/gotenberg/boot-and-discovery/ — tự động ráp nối của framework.