Руководство разработчика по Gotenberg

Кратко

Пакет Gotenberg делегирует преобразование в Portable Document Format (PDF) внешней службе. В коде приложения явно фиксируйте эту границу службы: проверяйте входные данные, формируйте полезную нагрузку, отправляйте запрос, разбирайте результат и обрабатывайте сбои службы.

Используйте это руководство при создании процессов преобразования офисных документов в PDF, конечных точек загрузки, проверок работоспособности службы или транспортной политики для nextpdf/gotenberg.

Граница архитектуры

Слой	Кому принадлежит	Ответственность	Что не размещать здесь
Источник загрузки или документа	Приложение	Авторизует вызывающую сторону, проверяет источник и выбирает политику преобразования.	Выбор конечной точки службы или закрепления транспорта.
Определение формата	nextpdf/gotenberg	Сопоставляет безопасные расширения с OfficeFormat.	Доверие к заявленным типам мультимедиа без проверки на стороне приложения.
Мост	nextpdf/gotenberg	Формирует составной (multipart) запрос, вызывает Gotenberg и разбирает ответ в формате PDF.	Запросы предметной области или политика хранения.
Служба Gotenberg	развёртывание	Преобразует офисный документ в PDF.	Авторизация приложения Hypertext Preprocessor (PHP).
Базовый движок	nextpdf/nextpdf	Импортирует или объединяет преобразованные данные PDF при необходимости.	Преобразование офисных документов.

Жизненный цикл во время выполнения

Этап	Поведение	Действие разработчика
Создание конфигурации	Конечная точка application programming interface (API), тайм-аут, максимальный размер, ключ API и закрепления загружаются из конфигурации.	Храните конечную точку службы и токен вне исходного кода.
Проверка входных данных	Проверяются путь к файлу, размер файла, имя файла, расширение и безопасность Uniform Resource Locator (URL).	Отклоняйте неподдерживаемые входные данные до отправки.
Построение полезной нагрузки	GotenbergConvertPayload формирует данные составной формы (multipart).	Сохраняйте исходное имя файла только там, где это безопасно.
Запрос к службе	Мост отправляет запрос на /forms/libreoffice/convert.	Настройте тайм-аут и транспортную политику.
Разбор результата	GotenbergResponseParser::parse() возвращает байты PDF и метаданные.	Считайте ответы с ошибками и ответы не в формате PDF сбоями преобразования.

Рекомендуемая структура приложения

Путь	Назначение
app/Pdf/Conversion/*	Обёртка приложения вокруг GotenbergBridge.
app/Pdf/Uploads/*	Проверка загрузки, хранение и политика именования файлов.
app/Pdf/ConversionPolicy/*	Политика выбора размера, формата и службы.
tests/Pdf/Conversion/*	Тесты формата, файла, службы и транспорта.

Отделяйте проверку файлов от преобразования. Служба преобразования должна получать уже авторизованные входные данные, но всё равно полагаться на проверки пакета как на эшелонированную защиту.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

Шаблоны преобразования

Шаблон	API	Когда использовать	Ограничение
Преобразование по пути к файлу	GotenbergBridge::convertFile()	Документ уже сохранён на диске.	Путь должен быть доступен для чтения и одобрен политикой.
Преобразование байтов в памяти	GotenbergBridge::convertString()	У приложения уже есть байты из загрузки или объектного хранилища.	Определение формата по-прежнему зависит от имени файла.
Построение полезной нагрузки напрямую	GotenbergConvertPayload	Нужны составные (multipart) байты для тестов или собственного транспортного кода.	Генерируйте разделитель (boundary) независимо от пользовательского ввода.
Разбор ответа напрямую	GotenbergResponseParser::parse()	Собственным вызовам Hypertext Transfer Protocol (HTTP) по-прежнему нужен парсер пакета.	Нужно передать ожидаемый OfficeFormat.

Работоспособность и готовность

GotenbergBridge::isAvailable() — это сигнал готовности, а не ваша единственная защита во время выполнения. Служба может пройти проверку готовности и всё равно дать сбой при следующем преобразовании.

Проверка	Назначение	Эксплуатационное примечание
Корректность конфигурации	Обнаружение отсутствующей конечной точки API.	Проверяйте это при загрузке приложения или во время проверок развёртывания.
/health доступность	Проверка доступности службы.	Используйте это для панелей мониторинга готовности.
Преобразование небольшой фикстуры	Выявление сбойного поведения LibreOffice или регрессии службы.	Запускайте это в плановых дымовых тестах, а не при каждом запросе.
Мониторинг тайм-аутов	Обнаружение медленной работы службы.	Отслеживайте по формату и размеру файла.

Точки расширения

Точка расширения	Используйте её для	Ограничение
Рекомендация по стандартам PHP (PSR)-18 ClientInterface	Собственное поведение HTTP-клиента.	Поведение должно следовать семантике ответов и исключений PSR-18.
Фабрики PSR-17	Создание запроса и потока.	Требуются для построения моста.
HtmlSecurityPolicyInterface	Политика уровня разбора для входных данных Hypertext Markup Language (HTML).	Дополняет политику безопасности Gotenberg.
ResponseFactoryInterface	Построение ответа закреплённого транспорта cURL.	Требуется только при использовании транспортного пути пакета.
GotenbergSecurityPolicy	Проверка URL, размера файла, имени файла и закреплений.	Держите авторизацию приложения вне этого уровня.

Процесс разработки

1. Начните с convertString() в тестах, чтобы фикстуры оставались явными.
2. Добавляйте convertFile() только после того, как пути файловой системы будут под контролем.
3. Держите максимальный размер файла ниже лимитов службы и инфраструктуры.
4. Используйте isAvailable() для сигналов готовности, а не как замену обработки ошибок.
5. Записывайте в журнал имя файла, формат, размер, статус и длительность. Не записывайте в журнал байты документа.
6. Добавьте тесты тайм-аутов и режимов сбоев перед открытием конечных точек загрузки.

Обработка сбоев

Сбой	Где его следует обрабатывать	Рекомендуемая реакция
Неподдерживаемое расширение	Определение формата.	Отклоните до того, как отправите в службу.
Небезопасное имя файла	Политика безопасности.	Отклоните его и нормализуйте политику именования при загрузке.
Файл сверх допустимого размера	Политика загрузки и проверка в пакете.	Отклоните до того, как прочитаете или отправите крупные полезные нагрузки.
Gotenberg недоступен	Граница моста.	Верните ошибку приложения, допускающую повторную попытку, когда это уместно.
Ответ, отличный от PDF	Парсер ответов.	Считайте это сбоем преобразования и зафиксируйте статус службы.
Сбой проверки закрепления или URL	Транспортная политика.	Завершите отказом по принципу fail-closed и оповестите операторов.

Безопасные значения по умолчанию

Аспект	По умолчанию	Когда переопределять
Тайм-аут	30 секунд.	Увеличивайте только после того, как измерите реальную задержку службы.
Максимальный размер файла	52,428,800 байт.	Понизьте для публичных или многопользовательских конечных точек.
Ключ API	Пусто.	Задайте для частных развёртываний Gotenberg.
Поддерживаемые форматы	docx, xlsx, pptx, odt, ods, odp.	Добавляйте форматы только тогда, когда их поддерживают OfficeFormat и парсер.
Наборы закреплений	Пусто.	Добавляйте их вместе с резервными закреплениями и процедурой ротации.

Контрольный список тестирования

• Тесты формата охватывают поддерживаемые и неподдерживаемые расширения.
• Тесты файлов охватывают отсутствующие файлы, нечитаемые файлы, файлы сверх допустимого размера и небезопасные имена файлов.
• Тесты службы охватывают ответы, отличные от 2xx, недопустимые тела ответов и транспортные исключения.
• Тесты безопасности охватывают частные или недопустимые URL службы, когда политика их запрещает.
• Тесты тайм-аутов проверяют, что настроенный тайм-аут передаётся в транспорт.
• В тестах с фикстурами образцы документов должны быть небольшими и не содержать конфиденциальных данных.