Bắt đầu nhanh với NextPDF Gotenberg

Tổng quan nhanh

Hướng dẫn này chuyển đổi một tệp .docx sang Portable Document Format (PDF). Khi hoàn tất, bạn sẽ có ba thứ: một instance bridge hoạt động, một kết nối đến dịch vụ đã được xác minh, và một tệp PDF trên đĩa. Chương trình đầy đủ nằm trong kho lưu trữ tại examples/convert-office-to-pdf.php. Các đoạn mã bên dưới được lấy từ chương trình đó.

Hướng dẫn này bắt đầu bằng cách đơn giản nhất nhưng vẫn hoạt động được. Các chủ đề về môi trường production, bao gồm cách lấy secret, thử lại, thời gian chờ và khả năng quan sát, được trình bày trong /integrations/gotenberg/production-usage/.

Trước khi bắt đầu

Trước khi tiếp tục, hãy xác nhận ba điều sau:

1. Bạn đã chạy composer require nextpdf/gotenberg, đồng thời một client theo PHP Standards Recommendation (PSR)-18 cùng các factory PSR-17 đã được cài đặt. Xem /integrations/gotenberg/install/.
2. Một dịch vụ Gotenberg có thể truy cập được qua Hypertext Transfer Protocol Secure (HTTPS). Bridge từ chối URL http:// thuần trước khi bất kỳ yêu cầu nào rời khỏi tiến trình.
3. Bạn có một tệp mẫu ở một trong các định dạng sau: .docx, .xlsx, .pptx, .odt, .ods, hoặc .odp. Các phần mở rộng khác sẽ gây ra ValueError.

Bước 1 — mô tả dịch vụ

GotenbergConfig là một value object bất biến. Tối thiểu, nó cần URL gốc HTTPS cho dịch vụ Gotenberg của bạn:

use NextPDF\Gotenberg\GotenbergConfig;

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

Transport cURL được ghim sẽ áp dụng timeout làm thời gian chờ truyền tải, tính bằng giây. Khi apiKey không rỗng, bridge sẽ gửi nó dưới dạng Authorization: Bearer <token>. Để trống apiKey nếu bản triển khai Gotenberg của bạn không yêu cầu token.

Bước 2 — kết nối bridge

Truyền config và các thành phần PSR vào bridge. Đồng thời tiêm responseFactory để bật transport cURL với Domain Name System (DNS) và Transport Layer Security (TLS) được ghim:

use NextPDF\Gotenberg\GotenbergBridge;

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

Bridge không bao giờ tạo client Hypertext Transfer Protocol (HTTP) thay cho bạn. Hãy dùng client PSR-18 và các factory PSR-17 mà bạn đã cài đặt. Tệp ví dụ minh họa cách kết nối Guzzle trong một dòng chú thích.

Bước 3 — kiểm tra tình trạng sẵn sàng

Hãy kiểm tra dịch vụ trước khi bạn chuyển đổi một tệp. Lệnh thăm dò kiểm tra tính hợp lệ của URL mà không tạo lưu lượng mạng, sau đó gửi một yêu cầu HEAD đến <apiUrl>/health:

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

Với URL rỗng, URL không dùng HTTPS, địa chỉ riêng tư, hoặc bất kỳ lỗi mạng nào, isAvailable() trả về false (không bao giờ ném ngoại lệ). Trạng thái dưới 500 từ /health nghĩa là dịch vụ đang sẵn sàng.

Bước 4 — chuyển đổi

Gọi convertFile() với một đường dẫn trên đĩa. Bridge chuẩn hóa đường dẫn để chặn duyệt thư mục. Nó ánh xạ phần mở rộng sang một định dạng được hỗ trợ, kiểm tra kích thước và tên tệp, rồi gửi một yêu cầu multipart đến <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

Để chuyển đổi các byte đã có trong bộ nhớ, hãy dùng convertString(). Hãy truyền tên tệp gốc để bridge có thể phát hiện phần mở rộng:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Bước 5 — dùng kết quả

Kết quả gồm ba thành phần: các byte PDF, định dạng nguồn, và một phép kiểm tra tính hợp lệ:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() là true khi phần thân không rỗng và bắt đầu bằng %PDF. size() trả về độ dài tính bằng byte. Từ đây, PDF là một luồng thông thường mà bạn có thể truyền cho NextPDF để xử lý hậu kỳ.

Chương trình hoàn chỉnh

Chương trình đầy đủ, có thể chạy được nằm tại examples/convert-office-to-pdf.php trong kho lưu trữ của gói. Nó bao gồm phân tích đối số, cấu hình được điều khiển bằng biến môi trường, lệnh thăm dò tình trạng, xử lý lỗi đầy đủ, và bước ghi. Chạy nó bằng:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

Tiếp theo là gì

• /integrations/gotenberg/configuration/ — xem lại từng tùy chọn và các quy tắc chọn transport.
• /integrations/gotenberg/production-usage/ — xử lý secret, thử lại, thời gian chờ, ghi log, và xử lý đồng thời.
• /integrations/gotenberg/troubleshooting/ — hiểu rõ mọi ngoại lệ mà đoạn mã này có thể ném ra và ý nghĩa của chúng.
• /integrations/gotenberg/integration/ — điều khiển một pipeline kết xuất NextPDF thông qua dịch vụ.