Установка NextPDF Gotenberg

Кратко

Установка моста состоит из двух частей: PHP-пакета с HTTP-зависимостями PHP Standard Recommendation (PSR), которые устанавливаются через Composer, и сервиса Gotenberg, к которому обращается пакет. Мост преобразует файлы, передавая задания этому сервису, поэтому он не сможет выполнять преобразования, пока экземпляр Gotenberg недоступен.

Настройте обе части, прежде чем писать код преобразования.

Требования

Требование	Ограничение	Почему
PHP	>=8.4 <9.0	Указано в composer.json пакета.
Ядро NextPDF	^3.0	Указано в composer.json как прямая зависимость.
HTTP-клиент PSR-18	^1.0	Мост отправляет запросы через внедрённый Psr\Http\Client\ClientInterface.
HTTP-фабрики PSR-17	^1.1	Мост создаёт запросы и потоки через внедрённые фабрики PSR-17.
Логгер PSR-3	^3.0 (необязательно)	Вы можете внедрить логгер для отладочного логирования запросов.
Сервис Gotenberg	Доступен по HTTPS	Преобразование выполняет внешний сервис, а не этот пакет.

Мост не включает клиент PSR-18 или фабрики PSR-17. Выберите реализации, подходящие вашему приложению. Например, используйте клиент на основе Guzzle вместе с его фабриками PSR-17 или HTTP-клиент Symfony с nyholm/psr7. Подойдёт любая реализация, соответствующая нужным контрактам PSR: мост зависит от интерфейсов, а не от конкретной библиотеки.

Шаг 1 — установка пакета

Добавьте пакет с помощью Composer:

composer require nextpdf/gotenberg

Composer разрешает nextpdf/core ^3.0 и контракты PSR HTTP: psr/http-client, psr/http-factory и psr/log. При этом он не устанавливает конкретный HTTP-клиент.

Шаг 2 — установка клиента PSR-18 и фабрик PSR-17

Установите один клиент PSR-18 и совместимый набор фабрик PSR-17. С Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Или с HTTP-клиентом Symfony и Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Передайте эти реализации в конструктор моста. Мост никогда не создаёт HTTP-клиент самостоятельно: вы выбираете реализацию при сборке моста. Структура конструктора описана в /integrations/gotenberg/configuration/, а полный пример сборки — в /integrations/gotenberg/quickstart/.

Шаг 3 — развёртывание сервиса Gotenberg

Мост обращается к маршруту преобразования LibreOffice в Gotenberg, поэтому запустите экземпляр Gotenberg, доступный мосту. Вышестоящий проект публикует контейнерный образ. Для локальной разработки используйте:

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

Так Gotenberg будет доступен на порту 3000 по обычному HTTP. Используйте это только для локальной разработки. Мост требует HTTPS для настроенного URL API и отклоняет обычный http:// до отправки любого запроса. Для всего, что выходит за рамки локального эксперимента, разместите Gotenberg за обратным прокси или сервисной сеткой, которые завершают Transport Layer Security (TLS), а затем укажите мосту конечную точку HTTPS. /integrations/gotenberg/security-and-operations/ описывает схему развёртывания в продакшене, сетевую доступность и аутентификацию.

Показанный здесь тег образа (gotenberg/gotenberg:8) относится к вышестоящей мажорной линии Gotenberg. README этого проекта и базовая интеграция ссылаются на эту линию. В продакшене закрепляйте конкретный патч-тег, а не отслеживайте подвижный мажорный тег. Также проверьте пути маршрутов (/forms/libreoffice/convert, /health) для версии Gotenberg, которую вы развёртываете. Мост предполагает эти два пути и больше ничего не предполагает о сервисе.

Шаг 4 — проверка сборки

К этому моменту пакет и HTTP-клиент установлены, а Gotenberg доступен по HTTPS. Прежде чем запускать реальное преобразование, убедитесь через встроенную проверку работоспособности, что мост может обратиться к сервису:

<?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() сначала проверяет настроенный URL. Он возвращает false для пустого URL, URL без HTTPS или URL с частным адресом без отправки сетевого трафика. Затем он отправляет запрос HEAD на <apiUrl>/health и считает сервис доступным, если статус ниже 500. При сетевой ошибке мост перехватывает её и сообщает о недоступности сервиса, а не выбрасывает исключение.

Примечание о версии

Эта документация описывает пакет на линии ^3.0. Линия соответствует требованию composer.json и матрице поддержки SECURITY.md, где 3.x поддерживается, а 2.x — нет. Более ранние ссылки на 0.x на каркасных страницах внутри репозитория появились до линии 3.0. Ограничение composer.json имеет приоритет над ними.

См. также

• /integrations/gotenberg/overview/ — что делает мост и какие форматы преобразует.
• /integrations/gotenberg/configuration/ — каждый аргумент конструктора и поле конфигурации.
• /integrations/gotenberg/quickstart/ — полный рабочий пример первого преобразования.
• /integrations/gotenberg/security-and-operations/ — как безопасно эксплуатировать зависимость от Gotenberg.
• /integrations/gotenberg/boot-and-discovery/ — автоматическая сборка во фреймворке.