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

Кратко

Конфигурация состоит из двух частей: неизменяемого объекта-значения GotenbergConfig, который описывает сервис и его ограничения, и конструктора GotenbergBridge, который получает PHP Standard Recommendation (PSR)-зависимости для Hypertext Transfer Protocol (HTTP). Оба компонента передаются явным внедрением через конструктор. У пакета нет глобального состояния, он не читает переменные окружения и не задаёт скрытую конечную точку по умолчанию.

Объект конфигурации

GotenbergConfig — это объект-значение final readonly. Создайте его напрямую с помощью именованных аргументов или постройте из ассоциативного массива через GotenbergConfig::fromArray().

Поля

Поле	Тип	По умолчанию	Эффект
apiUrl	string	''	Базовый Uniform Resource Locator (URL) сервиса Gotenberg. Обязателен: пустое значение делает конфигурацию недействительной, а каждое преобразование сразу завершается ошибкой. Должен использовать Hypertext Transfer Protocol Secure (HTTPS).
timeout	int	30	Строгий тайм-аут передачи в секундах. Транспорт с привязкой на основе cURL применяет его, если выбран.
maxFileSize	int	52_428_800	Максимальный размер входных данных в байтах (50 МиБ). Входные данные больше этого размера отклоняются до отправки любого запроса.
apiKey	string	''	Bearer-токен. Если он не пуст, отправляется как заголовок Authorization: Bearer <token>. Помечен #[\SensitiveParameter], поэтому скрывается в трассировках стека.
pinnedPublicKeys	list<string>	[]	Основные привязки Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) в форме sha256/<base64>. Пустое значение отключает привязку.
backupPublicKeys	list<string>	[]	Резервные привязки TLS SPKI. Хранятся отдельно, чтобы ротацию можно было проверять независимо.

Прямое создание

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

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

Создание из массива

fromArray() принимает ключи в snake_case и игнорирует некорректные значения вместо того, чтобы выбрасывать исключение. Нестроковый api_url становится ''. Нецелочисленный timeout возвращается к значению 30. Нецелочисленный max_file_size возвращается к значению по умолчанию в 50 МиБ. Списки привязок не в виде массивов становятся []. Нестроковые элементы внутри массивов привязок отбрасываются.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Такой мягкий разбор сделан намеренно. Вы можете передать массив конфигурации фреймворка напрямую, без отдельной предварительной проверки, и всё равно получить объект со строгими типами. Метод не проверяет, доступен ли URL и верны ли привязки. Эти проверки мост выполняет во время преобразования.

Действительность

isValid() возвращает true, только если apiUrl — непустая строка. Метод не выполняет сетевых проверок или проверок схемы. HTTPS и фильтрацию приватных адресов обрабатывает политика безопасности во время преобразования. Если конфигурация недействительна, convertFile() и convertString() выбрасывают GotenbergConvertException с сообщением Invalid Gotenberg configuration: apiUrl is empty. При недействительной конфигурации isAvailable() также возвращает false без какого-либо сетевого вызова.

Конструктор моста

GotenbergBridge получает конфигурацию и PSR-зависимости:

Аргумент	Тип	Обязательный	Эффект
config	GotenbergConfig	да	Описание сервиса и ограничения, перечисленные выше.
httpClient	Psr\Http\Client\ClientInterface	да	Клиент PSR-18, используемый для проверки работоспособности и резервного транспорта.
requestFactory	Psr\Http\Message\RequestFactoryInterface	да	Создаёт запрос PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	да	Создаёт поток тела запроса.
logger	Psr\Log\LoggerInterface|null	нет (по умолчанию null)	Если передан, записывает одну запись уровня debug на каждый запрос преобразования.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	нет	По умолчанию используется базовая политика безопасности Hypertext Markup Language (HTML). Применяется на этапе разбора и дополняет политику транспортного уровня.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	нет (по умолчанию null)	Требуется для активации транспорта с привязкой на основе cURL. Без него мост всегда использует внедрённый клиент PSR-18.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

Выбор транспорта

Мост поддерживает два транспорта и выбирает один для каждого запроса преобразования:

• Транспорт с привязкой на основе cURL — используется, когда внедрён responseFactory и есть данные для привязки (URL разрешился в один или несколько адресов Internet Protocol (IP) либо настроены привязки SPKI). Этот транспорт закрепляет набор разрешённых адресов с помощью CURLOPT_RESOLVE. Он применяет привязку SPKI с помощью CURLOPT_PINNEDPUBLICKEY, если привязки присутствуют. Он проверяет узел и хост (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Он применяет настроенный тайм-аут и отключает следование за перенаправлениями (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Внедрённый клиент PSR-18 — используется во всех остальных случаях, в том числе когда URL прикладного программного интерфейса (API) представляет собой простой публичный IP-литерал (нет Domain Name System (DNS) для привязки) и привязки SPKI не настроены, либо когда responseFactory не предоставлен.

Для соединений, устойчивых к DNS-rebinding, и привязки TLS внедрите responseFactory и настройте привязки. Проверка работоспособности всегда использует внедрённый клиент PSR-18 независимо от выбора транспорта.

Привязка открытых ключей TLS

Привязка использует модель отпечатка SPKI на основе Secure Hash Algorithm 256-bit (SHA-256). Каждая привязка — это строка в форме sha256/<base64-encoded-spki-hash>. Транспорт также принимает родную для cURL форму sha256//<base64> и преобразует в неё форму с одним слешем. Любой другой префикс вызывает InvalidSpkiPinException.

allPublicKeyPins() возвращает объединение без дубликатов pinnedPublicKeys и backupPublicKeys. Уровень TLS принимает сертификат, чей хеш SPKI совпадает с любым членом этого объединённого набора. В рабочей эксплуатации настройте хотя бы одну резервную привязку, чтобы запланированная ротация сертификата или ключа не лишила мост доступа к сервису, пока новый ключ распространяется. Хранение резервного списка отдельно от основного позволяет проверять и заменять резервную привязку независимо от активной. См. /integrations/gotenberg/security-and-operations/ для процедуры ротации.

Параметры преобразования для отдельного запроса

Тип multipart-полезной нагрузки (GotenbergConvertPayload) содержит файл и два необязательных параметра преобразования Gotenberg:

• landscape (bool, по умолчанию false) — отправляется как поле формы landscape со значением "true" или "false".
• nativePageRanges (string, по умолчанию '') — отправляется как поле формы nativePageRanges только если оно не пустое; поддерживает синтаксис диапазонов Gotenberg, например 1-3 или 1,3,5-9.

Публичные точки входа convertFile() и convertString() создают полезную нагрузку со значениями по умолчанию для обоих полей. Эти поля входят в контракт полезной нагрузки и покрыты набором тестов. Предоставьте к ним доступ в своём интеграционном слое, если вам нужен альбомный вывод или выбор страниц.

См. также

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