Справочник API Gotenberg

Кратко

Пакет Gotenberg предоставляет один сервисный мост — GotenbergBridge. Он преобразует офисный документ (docx, xlsx, pptx, odt, ods, odp) в Portable Document Format (PDF), отправляя POST-запрос во внешний сервис Gotenberg. Мост работает с объектами-значениями, которые вы передаёте в него или получаете из него: GotenbergConfig (неизменяемый дескриптор сервиса с ограничениями), OfficeFormat (перечисление поддерживаемых форматов), GotenbergConvertPayload (тело multipart-запроса) и GotenbergConvertResult (разобранный ответ с PDF). Внутренний слой — GotenbergSecurityPolicy, GotenbergResponseParser и PinnedCurlTransport — предоставляет проверку, разбор и транспорт с закреплением; мост управляет им сам. Используйте этот уровень только тогда, когда пишете собственный транспорт или тестовый код.

С чего начать: создайте GotenbergConfig с URL вашего сервиса по протоколу Hypertext Transfer Protocol Secure (HTTPS), затем передайте его в GotenbergBridge вместе с клиентом PSR-18 и фабриками PSR-17. Вызовите convertFile() или convertString(), затем прочитайте pdfData из возвращённого GotenbergConvertResult.

Типовые задачи

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

Преобразование файла с диска в PDF

Передайте мосту путь. Формат определяется по расширению.

<?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);

Что это делает: проверяет URL, путь, размер и имя файла, отправляет один multipart-запрос и записывает возвращённые байты PDF на диск.

Преобразование байтов из памяти в PDF

Используйте convertString(), когда байты уже у вас. Формат определяется по имени файла.

<?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.');
}

Что это делает: определяет xlsx по имени файла, преобразует байты и проверяет, что результат начинается с сигнатуры %PDF, прежде чем вы его используете.

Проверка готовности сервиса перед преобразованием

Проверяйте готовность через isAvailable(). Он проверяет URL без сетевого трафика, затем отправляет один запрос HEAD на /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Что это делает: возвращает false (никогда не выбрасывает исключение) для пустого URL, URL не по HTTPS или с приватным адресом, а также при любой сетевой ошибке, поэтому вы можете быстро остановиться до отправки преобразования.

Мост

Эта таблица описывает публичный интерфейс моста. Используйте её, когда создаёте GotenbergBridge или вызываете его методы преобразования и проверки готовности.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или ошибки	Примечания
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Конфигурация, клиент PSR-18, фабрики PSR-17, необязательный логгер, необязательная политика HTML, необязательная фабрика ответов.	Использует `DefaultHtmlSecurityPolicy`, если политика не передана.	`GotenbergBridge`	Ошибки связывания контейнера.	Фабрика ответов включает транспорт cURL с закреплением, когда оно требуется.
`GotenbergBridge::convertFile(string $filePath)`	Путь к офисному документу в файловой системе.	Использует расширение файла для определения формата.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` для неподдерживаемого формата.	Определяет реальный путь и проверяет читаемость, размер и имя файла.
`GotenbergBridge::convertString(string $content, string $fileName)`	Сырые байты и исходное имя файла.	Использует расширение имени файла для определения формата.	`GotenbergConvertResult`	То же, что у `convertFile`.	Используйте, если у приложения уже есть байты файла.
`GotenbergBridge::isAvailable()`	Нет.	Отправляет запрос HEAD на `/health`, если конфигурация валидна.	`bool`	Возвращает `false` при ошибках.	Только сигнал готовности.
`GotenbergBridge::getHtmlSecurityPolicy()`	Нет.	Возвращает настроенную политику слоя разбора.	`HtmlSecurityPolicyInterface`	Не ожидается.	Дополняет политику безопасности на уровне транспорта.

Конфигурация и полезные нагрузки

Эта таблица описывает объекты-значения, которые вы создаёте напрямую: дескриптор сервиса GotenbergConfig, а также объекты запроса и ответа GotenbergConvertPayload/GotenbergConvertResult. Используйте их, когда нужен более тонкий контроль, чем дают две точки входа преобразования.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или ошибки	Примечания
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL API, тайм-аут, максимальный размер файла, bearer-токен, наборы закреплений.	Пустой URL недопустим; максимальный размер по умолчанию — 50 МиБ.	`GotenbergConfig`	Не ожидается.	Храните ключ API в секрете.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, массивы закреплений.	Для отсутствующих необязательных значений используются значения конструктора по умолчанию.	`GotenbergConfig`	Не ожидается.	В строковых списках нестроковые значения игнорируются.
`GotenbergConfig::isValid()`	Нет.	Валидна, если URL API непустой.	`bool`	Не ожидается.	Безопасность URL проверяется до любой сетевой операции.
`GotenbergConfig::allPublicKeyPins()`	Нет.	Объединяет основные и резервные закрепления.	`list<string>`	Не ожидается.	Пустой список отключает закрепление.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Имя файла, байты, формат, флаг ориентации, диапазоны страниц.	Книжная ориентация; все страницы.	`GotenbergConvertPayload`	Не ожидается.	Полезная нагрузка преобразуется в данные формы multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Граница multipart.	Включает поле диапазона страниц, только если оно непустое.	`string`	Не ожидается.	Границу генерирует мост.
`GotenbergConvertPayload::contentType(string $boundary)`	Граница multipart.	Использует `multipart/form-data`.	`string`	Не ожидается.	Передайте как `Content-Type` запроса.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Преобразованные байты PDF, исходный формат, необязательная длительность отрисовки.	Если длительность отрисовки не измерена, она равна `0.0`.	`GotenbergConvertResult`	Не ожидается.	Возвращается методом `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	Нет.	Валиден, если преобразованные байты PDF непустые и выглядят как данные PDF.	`bool`	Не ожидается.	Проверяйте перед сохранением или потоковой передачей результата.
`GotenbergConvertResult::size()`	Нет.	Считает преобразованные байты PDF.	`int`	Не ожидается.	Используйте для квот, телеметрии и ограничений ответа.

Офисные форматы

Эта таблица описывает перечисление OfficeFormat. Используйте его, чтобы сопоставить расширение с форматом, получить MIME-тип для отправки или проверить, какие шесть форматов поддерживаются.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или ошибки	Примечания
`OfficeFormat::fromExtension(string $ext)`	Расширение файла с ведущей точкой или без неё.	Сопоставляет расширение без учёта регистра.	`OfficeFormat`	`ValueError` для неподдерживаемого расширения.	Поддерживаемые значения: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	Нет.	Сопоставляет вариант перечисления с MIME-типом для отправки.	`string`	Не ожидается.	Используется в файловой части multipart.
`OfficeFormat::extension()`	Нет.	Возвращает базовое значение перечисления.	`string`	Не ожидается.	Полезно для диагностики и имён файлов.

Безопасность, разбор и транспорт

Эта таблица описывает внутренние механизмы, которыми мост управляет сам. Используйте её только тогда, когда пишете собственный транспорт, выполняете собственный вызов по протоколу Hypertext Transfer Protocol (HTTP), для которого всё ещё нужен разбор средствами пакета, или исследуете низкоуровневое поведение безопасности и закрепления.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или ошибки	Примечания
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	Базовый URL API.	Разбирает и проверяет целевой адрес до любой сетевой операции.	`array`	`RuntimeException` для небезопасных или недопустимых URL.	Отсекает ошибки конечных точек в стиле server-side request forgery (SSRF) до кода преобразования.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Хост и список закреплённых адресов Internet Protocol (IP).	Проверяет ожидаемые закрепления Domain Name System (DNS).	`void`	`RuntimeException`, когда закрепления устарели или недопустимы.	Используйте в развёртываниях с закреплением и для эксплуатационной диагностики.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Фактический размер и настроенный максимум.	Принимает файлы, размер которых не превышает настроенное ограничение.	`void`	`RuntimeException`, когда файл слишком велик.	Применяйте до построения запроса.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Исходное имя файла.	Отклоняет небезопасные или неподдерживаемые варианты имени файла.	`void`	`RuntimeException` для недопустимых имён.	Предотвращает некорректные имена файлов в multipart.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Ответ PSR-7 и ожидаемый офисный формат.	Извлекает преобразованные байты PDF из успешного ответа.	`GotenbergConvertResult`	`GotenbergConvertException` для неуспешных ответов или недопустимого вывода PDF.	Основной парсер для преобразования файлов и строк.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Фабрики PSR-17, закреплённые IP, закреплённые открытые ключи, тайм-аут.	Закреплений нет; тайм-аут 30 секунд.	`PinnedCurlTransport`	Не ожидается.	Используйте только тогда, когда требуется закрепление на уровне cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Запрос PSR-7.	Отправляет через cURL с настроенным тайм-аутом и проверками закрепления.	`ResponseInterface`	`GotenbergConvertException` при сбое cURL/транспорта.	Используйте, когда закрепление нельзя делегировать другому HTTP-клиенту.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Запрос, хост и порт.	Формирует массив параметров cURL, который использует `sendRequest()`.	`array`	Ошибки из-за недопустимого запроса или конфигурации закрепления.	Для низкоуровневой диагностики и тестов.

Заметки для разработки

Считайте Gotenberg границей внешнего сервиса. Осознанно задавайте тайм-аут, размер, URL и политику закрепления.
convertFile() читает весь файл в память до построения запроса.
Логируйте метаданные, например имя файла и длину содержимого, а не содержимое файла.