Загрузка и обнаружение моста NextPDF Gotenberg

Кратко

У моста нет механизма автоматического обнаружения. Вы собираете его как обычный сервис и явно внедряете через конструктор: объект-значение конфигурации и компоненты Hypertext Transfer Protocol (HTTP), определённые в PHP Standard Recommendation (PSR). Этот пакет не поставляет ни сервис-провайдера, ни бандла, ни расширения контейнера и сам не читает переменные окружения. Здесь “обнаружение” означает способ, которым хост-фреймворк предоставляет эти компоненты. За это отвечает фреймворк, а не данный пакет.

Как обнаруживается мост

Он не обнаруживается автоматически. Вы собираете его сами. GotenbergBridge требует четыре аргумента и принимает три необязательных:

Обязательные: GotenbergConfig, клиент PSR-18, фабрика запросов PSR-17 и фабрика потоков PSR-17.
Необязательные: логгер PSR-3, политика безопасности Hypertext Markup Language (HTML) (по умолчанию используется стандартная политика ядра NextPDF) и фабрика ответов PSR-17.

Фабрика ответов активирует транспорт с закреплением через cURL. Если вы её передадите и у моста будет что закреплять (разрешённые адреса или настроенные закрепления SubjectPublicKeyInfo (SPKI)), он использует транспорт с закреплением. Если вы её не передадите, всегда используется внедрённый клиент PSR-18. Полный контракт аргументов приведён в /integrations/gotenberg/configuration/.

Последовательность загрузки

Отдельного этапа регистрации нет. Жизненный цикл выглядит так:

Хост разрешает клиент PSR-18 и фабрики PSR-17. Это делает контейнер хоста, а не пакет.
Приложение собирает GotenbergConfig из своего источника конфигурации. GotenbergConfig::fromArray() принимает массив в формате snake_case и подставляет значения по умолчанию для некорректных значений. Проверяйте источник на этапе загрузки, чтобы отсутствующее значение Uniform Resource Locator (URL) вызывало ошибку при загрузке, а не при каждом преобразовании.
Приложение собирает GotenbergBridge с конфигурацией и зависимостями.
При первом вызове преобразования выполняются проверка URL, проверка на подделку серверного запроса (server-side request forgery, SSRF), проверка имени файла и сам запрос. На этапе сборки ничего не выполняется: мост бездействует, пока вы его не вызовете.

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

Этот пакет не поставляет привязки контейнера. Чтобы мост можно было внедрять как зависимость, зарегистрируйте его в контейнере вашего хост-приложения следующим образом:

Привяжите GotenbergConfig, созданный из вашего источника конфигурации.
Привяжите клиент PSR-18 и фабрики PSR-17 к выбранным вами реализациям.
Привяжите GotenbergBridge как сервис, который получает эти зависимости.

Автоматическое связывание, публикация конфигурации и регистрация сервис-провайдера или бандла средствами конкретного фреймворка относятся к специализированным пакетам интеграции с фреймворком, а не к этому пакету. Этот пакет по своей конструкции не зависит от фреймворка. Он зависит только от интерфейсов PSR, поэтому работает с любым контейнером.

Порядок разрешения конфигурации

Пакет сам не читает конфигурацию. Порядок разрешения задаёт ваше приложение перед вызовом GotenbergConfig::fromArray() или конструктора. Распространённый порядок: сначала переменные окружения, затем опубликованный файл конфигурации, затем значения по умолчанию в коде. Этот порядок — контракт вашего приложения, а не данного пакета. Пакет определяет только значение по умолчанию для каждого поля, отсутствующего в массиве, переданном в fromArray(): пустой URL программного интерфейса приложения (application programming interface, API), тайм-аут 30 секунд, ограничение размера 50 MiB, пустой ключ API и пустые списки закреплений.

Диагностика

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

isAvailable() проверяет URL без сетевого трафика, затем отправляет запрос HEAD на <apiUrl>/health и сообщает о доступности, если статус ниже 500. При любом сбое он возвращает false, а не выбрасывает исключение. Вызывайте его в проверке готовности.
Контрольное преобразование заведомо корректного небольшого документа подтверждает весь путь от начала до конца. Сюда входят составной запрос (multipart) на <apiUrl>/forms/libreoffice/convert и проверка ответа.

См. также

/integrations/gotenberg/integration/ — управление конвейером NextPDF через сервис.
/integrations/gotenberg/install/ — установка пакета и сервиса.
/integrations/gotenberg/configuration/ — полный контракт конструктора и конфигурации.
/integrations/gotenberg/overview/ — поток преобразования и модель зависимостей.