Интеграция NextPDF с Gotenberg

Кратко

На этой странице показано, как подключить мост к остальной части приложения. Установите пакет, подключите мост, а затем передайте преобразованный PDF в конвейер постобработки NextPDF. Мост преобразует документ Office в PDF; конвейер обрабатывает всё, что происходит после преобразования. Как устроена эта схема подключения, см. /integrations/gotenberg/boot-and-discovery/.

Установка

composer require nextpdf/gotenberg

Вместе с этим пакетом устанавливаются nextpdf/core ^3.0 и контракты PHP Standards Recommendation (PSR) для Hypertext Transfer Protocol (HTTP). Установите клиент PSR-18 и фабрики PSR-17 отдельными пакетами. Мост зависит только от интерфейсов, поэтому вы можете выбрать конкретные библиотеки. Полные шаги установки, включая запуск службы Gotenberg по Hypertext Transfer Protocol Secure (HTTPS), см. /integrations/gotenberg/install/.

Подключение

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

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Мост требует HTTPS для настроенного URL. Он отклоняет обычный http:// ещё до отправки какого-либо запроса. Запустите Gotenberg за точкой завершения TLS, а затем направьте мост на HTTPS-конечную точку.

Привязки контейнера

Зарегистрируйте в контейнере хоста три записи: GotenbergConfig, созданный из вашего источника конфигурации, ваш клиент PSR-18 вместе с фабриками PSR-17 и GotenbergBridge, собранный из этих зависимостей. Этот пакет не поставляет собственные привязки. Регистрацию через конкретный фреймворк должны выполнять специализированные пакеты интеграции с фреймворками. См. /integrations/gotenberg/boot-and-discovery/.

Конфигурация

Все поля дескриптора службы и его ограничения находятся в GotenbergConfig. Они охватывают URL программного интерфейса приложения (API), тайм-аут, предельный размер, токен Bearer и пины TLS. Параметры уровня запроса, такие как landscape и nativePageRanges, находятся не здесь, а в типе полезной нагрузки. /integrations/gotenberg/configuration/ описывает каждое поле, его тип, значение по умолчанию и эффект.

Передача преобразованного PDF в конвейер NextPDF

Типичный сквозной процесс:

1. Преобразуйте документ Office с помощью convertFile() или convertString().
2. Возьмите $result->pdfData с необработанными байтами PDF и загрузите их в документ NextPDF.
3. Примените постобработку, например сборку страниц, добавление водяных знаков, преобразование в PDF/A или цифровые подписи.

Шаг 3 относится к NextPDF, а не к мосту. Пакет nextpdf/premium предоставляет подписание, профили PDF/A и добавление водяных знаков. Оставляйте преобразование и постобработку отдельными этапами, чтобы вы могли диагностировать каждый сбой отдельно.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

В выпуске Pro поддержка PDF Advanced Electronic Signatures (PAdES) ограничена базовым уровнем B-B. Она не предоставляет B-T, B-LT или B-LTA. Преобразование документа через этот мост не подразумевает возможностей проставления меток времени или долгосрочной проверки.

Дымовая проверка

После подключения проверьте интеграцию, не преобразуя реальный документ:

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

isAvailable() проверяет URL без сетевого трафика. Затем метод отправляет запрос HEAD на <apiUrl>/health. После этого преобразуйте один заведомо корректный небольшой документ. Это задействует полный multipart-путь к <apiUrl>/forms/libreoffice/convert и проверяет ответ.

Точки входа публичного API

Публичный интерфейс, используемый этой интеграцией:

• GotenbergConfig — неизменяемый дескриптор службы и ограничения; fromArray() создаёт его из массива конфигурации.
• GotenbergBridge::convertFile(string $path) — преобразует файл на диске.
• GotenbergBridge::convertString(string $bytes, string $fileName) — преобразует байты, находящиеся в памяти.
• GotenbergBridge::isAvailable() — проверка готовности, не выбрасывающая исключений.
• GotenbergConvertResult — содержит pdfData, sourceFormat, isValid() и size().
• GotenbergConvertException — тип исключения уровня преобразования.

Полный контракт описан в /integrations/gotenberg/configuration/ и /integrations/gotenberg/troubleshooting/. Он включает выбор транспорта и каталог исключений.

См. также

• /integrations/gotenberg/boot-and-discovery/ — почему схема подключения выглядит именно так.
• /integrations/gotenberg/quickstart/ — первое преобразование с пошаговым руководством.
• /integrations/gotenberg/production-usage/ — секреты, повторные попытки, тайм-ауты, наблюдаемость.
• /integrations/gotenberg/install/ — установка пакета и службы Gotenberg.