Tài liệu tham khảo API Gotenberg

Tổng quan

Gói Gotenberg cung cấp một bridge dịch vụ, GotenbergBridge. Bridge này chuyển tài liệu Office (docx, xlsx, pptx, odt, ods, odp) sang Portable Document Format (PDF) bằng cách gửi yêu cầu POST đến một dịch vụ Gotenberg bên ngoài. Bridge làm việc với các đối tượng giá trị mà bạn truyền vào hoặc đọc ra: GotenbergConfig (bộ mô tả dịch vụ và các giới hạn bất biến), OfficeFormat (enum cho các định dạng được hỗ trợ), GotenbergConvertPayload (phần thân yêu cầu multipart), và GotenbergConvertResult (phản hồi PDF đã được phân tích cú pháp). Một tầng thứ hai gồm GotenbergSecurityPolicy, GotenbergResponseParser và PinnedCurlTransport cung cấp cơ chế xác thực, phân tích cú pháp và truyền tải có ghim mà bridge điều khiển nội bộ. Chỉ dùng tầng này khi bạn viết mã truyền tải tùy chỉnh hoặc mã kiểm thử.

Bắt đầu tại đây: Tạo một GotenbergConfig bằng URL dịch vụ Hypertext Transfer Protocol Secure (HTTPS) của bạn, rồi truyền nó vào một GotenbergBridge cùng với client PSR-18 và các factory PSR-17. Gọi convertFile() hoặc convertString(), rồi đọc pdfData từ GotenbergConvertResult được trả về.

Tác vụ thường gặp

Hãy dùng các đoạn mã đã được kiểm chứng và có thể chạy này cho những tác vụ bạn nhiều khả năng sẽ thực hiện với gói.

Chuyển một tệp trên đĩa sang PDF

Trỏ bridge đến một đường dẫn. Bridge nhận diện định dạng từ phần mở rộng.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

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

Nó làm gì: xác thực URL, đường dẫn, kích thước và tên tệp; gửi yêu cầu multipart; rồi ghi các byte PDF được trả về xuống đĩa.

Chuyển byte trong bộ nhớ sang PDF

Dùng convertString() khi bạn đã có sẵn các byte. Tên tệp quyết định cách nhận diện định dạng.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

Nó làm gì: nhận diện xlsx từ tên tệp, chuyển đổi các byte, và xác nhận kết quả bắt đầu bằng chữ ký %PDF trước khi bạn dùng.

Kiểm tra mức sẵn sàng của dịch vụ trước khi chuyển đổi

Hãy chặn công việc bằng isAvailable(). Phương thức này xác thực URL mà không tạo lưu lượng mạng, rồi gửi yêu cầu HEAD đến /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Nó làm gì: trả về false (không bao giờ ném ngoại lệ) cho URL rỗng, không phải HTTPS, hoặc địa chỉ riêng tư, cũng như cho mọi lỗi mạng; nhờ đó bạn có thể dừng sớm trước khi gửi một lượt chuyển đổi.

Bridge

Bảng này bao quát bề mặt của bridge. Hãy dùng bảng này khi bạn khởi tạo GotenbergBridge hoặc gọi các phương thức chuyển đổi và kiểm tra mức sẵn sàng của nó.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, client PSR-18, các factory PSR-17, logger tùy chọn, chính sách HTML tùy chọn, response factory tùy chọn.	Dùng `DefaultHtmlSecurityPolicy` khi bạn không cung cấp chính sách.	`GotenbergBridge`	Lỗi nối dây trong container.	Response factory bật truyền tải cURL có ghim khi cần ghim.
`GotenbergBridge::convertFile(string $filePath)`	Đường dẫn trên hệ thống tệp tới một tài liệu Office.	Dùng phần mở rộng của tệp để nhận diện định dạng.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` đối với định dạng không được hỗ trợ.	Phân giải đường dẫn thực và kiểm tra khả năng đọc, kích thước và tên tệp.
`GotenbergBridge::convertString(string $content, string $fileName)`	Các byte thô và tên tệp gốc.	Dùng phần mở rộng của tên tệp để nhận diện định dạng.	`GotenbergConvertResult`	Giống như `convertFile`.	Dùng khi ứng dụng của bạn đã có sẵn các byte của tệp.
`GotenbergBridge::isAvailable()`	không.	Gửi HEAD đến `/health` khi config hợp lệ.	`bool`	Trả về `false` khi có lỗi.	Chỉ là tín hiệu mức sẵn sàng.
`GotenbergBridge::getHtmlSecurityPolicy()`	không.	Trả về chính sách của tầng phân tích cú pháp đã cấu hình.	`HtmlSecurityPolicyInterface`	không có gì dự kiến.	Bổ trợ cho chính sách bảo mật ở cấp truyền tải.

Cấu hình và payload

Bảng này bao quát các đối tượng giá trị mà bạn tự xây dựng: bộ mô tả dịch vụ GotenbergConfig cùng các bộ chứa yêu cầu và phản hồi GotenbergConvertPayload/GotenbergConvertResult. Hãy dùng chúng khi bạn cần kiểm soát chi tiết hơn những gì hai điểm vào chuyển đổi cung cấp.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL của API, timeout, kích thước tệp tối đa, bearer token, các tập ghim.	URL rỗng không hợp lệ; kích thước tối đa mặc định là 50 MiB.	`GotenbergConfig`	không có gì dự kiến.	Hãy giữ bí mật API key.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, các mảng ghim.	Các giá trị tùy chọn bị thiếu sẽ dùng mặc định của constructor.	`GotenbergConfig`	không có gì dự kiến.	Danh sách chuỗi sẽ bỏ qua các giá trị không phải chuỗi.
`GotenbergConfig::isValid()`	không.	Hợp lệ khi URL của API không rỗng.	`bool`	không có gì dự kiến.	Tính an toàn của URL được xác thực trước bất kỳ thao tác mạng nào.
`GotenbergConfig::allPublicKeyPins()`	không.	Kết hợp các ghim chính và ghim dự phòng.	`list<string>`	không có gì dự kiến.	Một danh sách rỗng sẽ tắt việc ghim.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Tên tệp, các byte, định dạng, cờ hướng trang, các khoảng trang.	Khổ dọc; tất cả các trang.	`GotenbergConvertPayload`	không có gì dự kiến.	Payload được chuyển thành dữ liệu form multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Ranh giới multipart.	Chỉ bao gồm trường khoảng trang khi nó không rỗng.	`string`	không có gì dự kiến.	Bridge tạo ra ranh giới.
`GotenbergConvertPayload::contentType(string $boundary)`	Ranh giới multipart.	Dùng `multipart/form-data`.	`string`	không có gì dự kiến.	Đính kèm dưới dạng `Content-Type` của yêu cầu.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Các byte PDF đã chuyển đổi, định dạng nguồn, thời lượng kết xuất tùy chọn.	Thời lượng kết xuất là `0.0` khi nó không được đo.	`GotenbergConvertResult`	không có gì dự kiến.	Được trả về bởi `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	không.	Hợp lệ khi các byte PDF đã chuyển đổi không rỗng và trông giống dữ liệu PDF.	`bool`	không có gì dự kiến.	Hãy kiểm tra trước khi lưu trữ hoặc truyền phát kết quả.
`GotenbergConvertResult::size()`	không.	Đếm các byte PDF đã chuyển đổi.	`int`	không có gì dự kiến.	Hãy dùng phương thức này cho hạn mức, dữ liệu đo từ xa và giới hạn phản hồi.

Định dạng Office

Bảng này bao quát enum OfficeFormat. Hãy dùng nó để ánh xạ phần mở rộng thành định dạng, đọc kiểu MIME tải lên của định dạng đó, hoặc kiểm tra sáu định dạng được hỗ trợ.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`OfficeFormat::fromExtension(string $ext)`	Phần mở rộng của tệp, có hoặc không có dấu chấm đứng đầu.	So khớp không phân biệt chữ hoa chữ thường.	`OfficeFormat`	`ValueError` đối với phần mở rộng không được hỗ trợ.	Các giá trị được hỗ trợ là: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	không.	Ánh xạ trường hợp của enum thành kiểu MIME tải lên.	`string`	không có gì dự kiến.	Được dùng trong phần tệp của multipart.
`OfficeFormat::extension()`	không.	Trả về giá trị nền tảng.	`string`	không có gì dự kiến.	Hữu ích cho chẩn đoán và tên tệp.

Bảo mật, phân tích cú pháp và truyền tải

Bảng này bao quát cơ chế nội bộ mà bridge điều khiển thay cho bạn. Chỉ dùng cơ chế này khi bạn viết mã truyền tải tùy chỉnh, thực hiện một lệnh gọi Hypertext Transfer Protocol (HTTP) tùy chỉnh nhưng vẫn cần gói phân tích cú pháp, hoặc xem xét hành vi bảo mật và ghim ở cấp thấp.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL cơ sở của API.	Phân tích cú pháp và xác thực đích đến trước bất kỳ thao tác mạng nào.	`array`	`RuntimeException` đối với các URL không an toàn hoặc không hợp lệ.	Giúp mã chuyển đổi tránh các lỗi điểm cuối kiểu giả mạo yêu cầu phía máy chủ (SSRF).
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host và danh sách Internet Protocol (IP) đã ghim.	Xác minh các kỳ vọng ghim Domain Name System (DNS).	`void`	`RuntimeException` khi các ghim đã cũ hoặc không hợp lệ.	Hãy dùng phương thức này trong các triển khai có ghim và chẩn đoán vận hành.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Kích thước thực tế và mức tối đa đã cấu hình.	Chấp nhận các tệp bằng hoặc nhỏ hơn giới hạn đã cấu hình.	`void`	`RuntimeException` khi tệp quá lớn.	Hãy thực thi trước khi dựng yêu cầu.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Tên tệp gốc.	Từ chối các dạng tên tệp không an toàn hoặc không được hỗ trợ.	`void`	`RuntimeException` đối với các tên không hợp lệ.	Ngăn tên tệp multipart bị dị dạng.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Phản hồi PSR-7 và định dạng Office mong đợi.	Trích xuất các byte PDF đã chuyển đổi từ phản hồi thành công.	`GotenbergConvertResult`	`GotenbergConvertException` đối với các phản hồi thất bại hoặc đầu ra PDF không hợp lệ.	Bộ phân tích cú pháp trung tâm cho chuyển đổi tệp và chuỗi.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Các factory PSR-17, các IP đã ghim, các khóa công khai đã ghim, timeout.	Không có ghim và timeout 30 giây.	`PinnedCurlTransport`	không có gì dự kiến.	Chỉ dùng khi cần ghim ở cấp cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Yêu cầu PSR-7.	Gửi qua cURL với timeout đã cấu hình và các kiểm soát ghim.	`ResponseInterface`	`GotenbergConvertException` khi cURL/truyền tải thất bại.	Hãy dùng phương thức này khi không thể ủy quyền việc ghim cho một client HTTP khác.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Yêu cầu, host và cổng.	Dựng mảng tùy chọn cURL mà `sendRequest()` sử dụng.	`array`	Lỗi yêu cầu không hợp lệ hoặc cấu hình ghim.	Chẩn đoán cấp thấp và hook kiểm thử.

Ghi chú phát triển

Hãy coi Gotenberg như một ranh giới dịch vụ bên ngoài. Thiết lập timeout, kích thước, URL và chính sách ghim một cách cẩn trọng.
convertFile() đọc toàn bộ tệp vào bộ nhớ trước khi dựng yêu cầu.
Hãy ghi nhật ký siêu dữ liệu như tên tệp và độ dài nội dung, không phải nội dung tệp.