Быстрый старт с NextPDF Gotenberg

Кратко

В этом руководстве вы преобразуете один файл .docx в Portable Document Format (PDF). В конце у вас будут три вещи: работающий экземпляр моста, проверенное соединение со службой и PDF на диске. Полная программа находится в репозитории по пути examples/convert-office-to-pdf.php. Приведённые ниже фрагменты взяты из неё.

Сначала показан самый простой рабочий путь. Темы, важные для продакшена, включая получение секретов, повторные попытки, тайм-ауты и наблюдаемость, рассматриваются в /integrations/gotenberg/production-usage/.

Перед началом

Перед продолжением проверьте три вещи:

1. Вы выполнили composer require nextpdf/gotenberg, и у вас установлены клиент PHP Standards Recommendation (PSR)-18 и фабрики PSR-17. См. /integrations/gotenberg/install/.
2. Служба Gotenberg доступна по протоколу Hypertext Transfer Protocol Secure (HTTPS). Мост отклоняет обычный http:// ещё до отправки запроса из процесса.
3. У вас есть образец файла в одном из этих форматов: .docx, .xlsx, .pptx, .odt, .ods или .odp. Для других расширений возникает ValueError.

Шаг 1 — опишите службу

GotenbergConfig — это неизменяемый объект-значение. Ему нужен как минимум базовый URL по HTTPS для вашей службы Gotenberg:

use NextPDF\Gotenberg\GotenbergConfig;

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

Закреплённый транспорт cURL применяет timeout как тайм-аут передачи в секундах. Если apiKey не пуст, мост отправляет его как Authorization: Bearer <token>. Оставьте apiKey пустым, если в вашем развёртывании Gotenberg токен не требуется.

Шаг 2 — подключите мост

Передайте конфигурацию и компоненты PSR в мост. Также передайте responseFactory, чтобы включить транспорт cURL с закреплением Domain Name System (DNS) и Transport Layer Security (TLS):

use NextPDF\Gotenberg\GotenbergBridge;

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

Мост никогда не создаёт за вас клиент Hypertext Transfer Protocol (HTTP). Используйте уже установленные клиент PSR-18 и фабрики PSR-17. В комментарии к файлу примера показано, как подключить Guzzle.

Шаг 3 — проверьте доступность

Проверьте службу, прежде чем преобразовывать файл. Проверка валидирует URL без сетевого трафика, затем отправляет запрос HEAD на <apiUrl>/health:

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

При пустом URL, URL не по HTTPS или с частным адресом, а также при любой сетевой ошибке isAvailable() возвращает false (никогда не выбрасывает исключение). Статус от /health ниже 500 означает, что служба доступна.

Шаг 4 — преобразуйте

Вызовите convertFile() и передайте путь на диске. Мост приводит путь к каноническому виду, чтобы заблокировать обход каталогов. Он сопоставляет расширение с поддерживаемым форматом, проверяет размер и имя файла, а затем отправляет составной запрос на <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;
}

Чтобы преобразовать байты, которые уже находятся в памяти, используйте convertString(). Передайте исходное имя файла, чтобы мост мог определить расширение:

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

Шаг 5 — используйте результат

Результат содержит три вещи: байты PDF, исходный формат и результат проверки валидности:

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() возвращает true, когда тело не пустое и начинается с %PDF. size() возвращает длину в байтах. После этого PDF — обычный поток, который можно передать в NextPDF для постобработки.

Полная программа

Полная программа, готовая к запуску, находится в examples/convert-office-to-pdf.php в репозитории пакета. Она включает разбор аргументов, конфигурацию на основе окружения, проверку работоспособности, полную обработку ошибок и запись результата. Запустите её так:

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

Что дальше

• /integrations/gotenberg/configuration/ — изучите все параметры и правила выбора транспорта.
• /integrations/gotenberg/production-usage/ — работайте с секретами, повторными попытками, тайм-аутами, журналированием и параллелизмом.
• /integrations/gotenberg/troubleshooting/ — узнайте, какие исключения может выбросить этот код и что они означают.
• /integrations/gotenberg/integration/ — управляйте конвейером отрисовки NextPDF через эту службу.