Руководство по выбору интеграции

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

Кратко

Экосистема NextPDF — это небольшой базовый движок и набор узкоспециализированных пакетов: мосты для фреймворков, два рендерера HTML, edge-рендерер и сервер исполнения. Эта страница сопоставляет реальные сценарии с подходящими пакетами и опирается на то, что каждый пакет действительно содержит. Выбор остаётся за вами и основан на фактах, а не на скрытых допущениях документации.

Почему это важно

Неверная интеграция обходится дорого, но это проявляется не сразу. Выберите удалённый браузерный рендерер там, где встроенный движок отрисовал бы документ корректно, — и добавите сетевой переход и зависимость от доступности для каждого PDF. Выберите встроенный движок для документа, которому действительно нужен полноценный браузерный движок компоновки, — и получите файл с едва заметными ошибками. Выбранный пакет определяет задержку, режимы отказа и эксплуатационную поверхность, поэтому это решение требует явного обоснования.

Если коротко

Начните с базового движка. Всё остальное только дополняет его. Если встроенный движок корректно отрисовывает ваш документ, пакет рендерера вам не нужен.
Мост для фреймворка следует за вашим фреймворком, а не за документом. Интеграции для Laravel, Symfony и CodeIgniter дают фасад или фабрику, PDF-ответ, генерацию в очереди и автообнаружение, но не меняют то, что способен отрисовать движок.
Используйте рендерер, только когда точность CSS требует браузера. Artisan (локальный Chrome) и Cloudflare (браузер на edge) существуют именно для этого; Gotenberg нужен, чтобы принимать документы Office на вход.
Используйте Connect, когда вызывающая сторона — сервис или ИИ-агент, а не вызов из PHP. Он открывает движок по MCP, REST и gRPC со шлюзом одобрения человеком для опасных операций.

Как NextPDF подходит к этому

Экосистема намеренно разделена на слои, чтобы у каждого пакета была одна задача. Базовый движок отрисовывает PDF в том же процессе. Мост для фреймворка адаптирует этот движок к идиомам фреймворка. Пакет рендерера делегирует компоновку HTML или Office внешнему движку, когда встроенный движок не справляется с задачей. Connect превращает движок в сетевой сервис. Ни один из этих пакетов не перекрывает зону ответственности другого, и поэтому решение остаётся управляемым. Вы не выбираете между конкурирующими инструментами. Вы собираете решение из взаимодополняющих частей.

Принимайте решение исходя из сценария. Таблица сопоставляет каждый сценарий с подходящим пакетом и показывает компромисс, на который вы идёте.

Сценарий	Подходящий пакет	Что он действительно предоставляет	Компромисс, на который вы идёте
PDF в приложении Laravel	`nextpdf/laravel`	Автообнаруживаемый поставщик служб, фасад `Pdf`, `PdfResponse` (inline/скачивание/потоковая передача, заголовки OWASP), задание в очереди `GeneratePdfJob` с tries/timeout/backoff, безопасные для Octane заблокированные реестры	Зависимость от Laravel 12; возможности движка не меняются
PDF в приложении Symfony	`nextpdf/symfony`	Автоматически регистрируемый бандл, внедряемый `PdfFactory`, `PdfResponse`, необязательный обработчик Messenger для асинхронной генерации	Зависимость от бандла Symfony 7.2; возможности не меняются
PDF в приложении CodeIgniter 4	`nextpdf/codeigniter`	`service('pdf')` / помощник `pdf()`, библиотека `Pdf`, оборачивающая одноразовый `Document`, `PdfResponse`, необязательное задание в очереди	Зависимость от CodeIgniter 4.6; возможности не меняются
Документу нужен полноценный браузерный CSS (flex/grid/веб-шрифты) рядом со встроенным процессом	`nextpdf/artisan`	Headless Chrome через CDP: страница отрисовывается, а затем импортируется обратно как Form XObject, поэтому текст остаётся выделяемым; пул браузеров	Среда выполнения Chrome и её расходы memory/process на вашем хосте
Документы Office (`.docx`, `.xlsx`) в PDF	`nextpdf/gotenberg`	Мост PSR-18 к микросервису Gotenberg с защищённым от SSRF транспортом, привязанным к IP	Внешний сервис Gotenberg и сетевая зависимость
HTML→PDF на edge / без локального Chrome	`nextpdf/cloudflare`	Cloudflare Browser Rendering через привязанный транспорт, с необязательным запасным вариантом на локальном Chrome	Аккаунт Cloudflare и сетевая зависимость; запасной вариант требует Artisan
Движок, который потребляет сервис или ИИ-агент	`nextpdf/server` (Connect)	Один движок по MCP (stdio), REST (OpenAPI 3.1) и gRPC; обнаружение инструментов через мягкие зависимости; шлюз подтверждения человеком для инструментов высокого риска	Эксплуатация сервисной поверхности; дисциплина детерминированного исполнения

Это два независимых решения, но их часто объединяют. Выбор моста для фреймворка определяется фреймворком, который вы уже используете, — он не расширяет и не ограничивает то, что отрисовывает движок. Выбор рендерера определяется документом. Решающий вопрос — хватает ли встроенного движка CSS или документу действительно нужен браузерный движок компоновки. Вам может понадобиться мост для фреймворка без рендерера, рендерер без моста, оба или ни одного. Когда их воспринимают как один вопрос, это становится самой частой ошибкой интеграции, поэтому эта страница их разделяет.

Что говорят факты

Эта страница носит редакционный характер: это решение о маршрутизации, но сама маршрутизация основана на том, что содержат манифест и основные классы каждого пакета.

Мосты реально существуют и устроены параллельно. Каждый объявляет свою зависимость от фреймворка и автоматическую регистрацию в своём composer.json (extra.laravel.providers, extra.symfony.bundles, Registrar в CodeIgniter). Каждый также поставляет PdfResponse, привязку одноразового документа и необязательное задание в очереди. Ни один из них не добавляет возможностей отрисовки — они адаптируют один и тот же движок. Рендереры тоже реальны и различаются между собой. Artisan зависит от chrome-php/chrome и импортирует PDF от Chrome обратно как Form XObject, чтобы текст оставался выделяемым. Gotenberg и Cloudflare — это HTTP-мосты PSR-18 с явно защищёнными от SSRF транспортами, привязанными к IP. Cloudflare может переключиться на Artisan, когда Worker недоступен. composer.json Connect объявляет три транспорта и модель мягких зависимостей: инструменты появляются по мере установки их пакетов и управляются четырёхуровневой моделью риска со шлюзом подтверждения человеком.

Форма, в которой эта страница направляет вас, подкреплена стандартами: Spec: ISO 24495-1:2023, §5 говорит, что читатели должны иметь возможность быстро определить, отвечает ли содержимое их цели, а Spec: ISO/IEC/IEEE 26514:2022, §3.x222 требует, чтобы ссылки и упоминания явно указывали назначение — поэтому в таблице названы конкретный пакет и компромисс, а не дано расплывчатое упоминание “некой интеграции”.

Практический пример

Это решение — последовательность честных вопросов, а не сравнение функций. Следующая схема разбирает распространённые случаи.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

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

Распространённое заблуждение

Преобладающее заблуждение — “мне нужен пакет рендерера, чтобы создавать PDF.” Это не так. Базовый движок создаёт PDF в том же процессе. Пакеты рендереров существуют только для конкретного случая, когда требуется браузерный движок компоновки или источник — документ Office. Когда встроенный движок уже создаёт корректный файл, рефлекторное подключение рендерера добавляет зависимость во время выполнения и режим отказа без всякой пользы.

Зеркальное заблуждение — “мост для фреймворка открывает возможности.” Это не так. Мост меняет то, как вы вызываете движок — фасад, фабрика, ответ, задание в очереди, — а не то, что он способен создать. Подписание, PDF/A и структурированные счета — это вопросы уровня лицензии и движка, одинаковые независимо от того, вызываете ли вы через мост или напрямую.

Ограничения и границы

Эта страница направляет; она не измеряет производительность и не ранжирует пакеты. Она указывает, что предоставляет каждый пакет и в чём компромисс. Выбор между ними вы принимаете с учётом своих ограничений.
Возможности пакетов взяты из их манифестов и основных классов на определённый момент времени. Актуальный API проверяйте по собственной документации каждого пакета. Это руководство — карта, а не спецификация.
Сравнение с конкурентами не предлагается и не подразумевается. Единственный предмет — это экосистема NextPDF и то, как её части сочетаются друг с другом.
Мост для фреймворка и рендерер — это независимые решения. Мост не расширяет возможности движка; рендерер не зависит от фреймворка.
Внешние рендереры добавляют зависимость от доступности. Gotenberg и Cloudflare добавляют сетевой вызов и сервис, который нужно эксплуатировать; это принятый компромисс, а не скрытая цена.
Возможности, зависящие от уровня лицензии, ортогональны интеграции. Коммерческие функции открываются уровнем лицензии, а не каким-либо мостом или рендерером; см. границу ниже.

Пакеты экосистемы и уровни лицензии — edition availability
Edition	Availability
Core	Каждый пакет интеграции (мосты, Artisan, Gotenberg, Cloudflare, Connect) работает с Core и распространяется под Apache-2.0. Они адаптируют движок или открывают к нему доступ; функций они не ограничивают.
Pro	Коммерческие возможности (базовое подписание PAdES, PDF/A, расширенные штрихкоды) открываются уровнем лицензии и затем доступны через любую интеграцию, а не сменой интеграции.
Enterprise	Структурированные счета, политики проверки и шлюз подтверждения человеком в Connect для инструментов высокого риска — это возможности уровня лицензии, и они тоже не зависят от интеграции.

Связанные документы

Конвейер HTML — что охватывает встроенный движок CSS, чтобы вы понимали, когда браузерный рендерер действительно нужен.
Когда не стоит использовать NextPDF — честная граница задач с документами, для которых движок не подходит.
Основы PHP 8.4 — минимальный уровень среды выполнения, общий для всех пакетов, и то, за счёт чего сохраняется путь обратного портирования.

Глоссарий

Базовый движок — nextpdf/core, встроенный движок PDF 2.0, на котором строится каждый другой пакет.
Мост для фреймворка — пакет интеграции (Laravel/Symfony/CodeIgniter), который адаптирует движок к идиомам фреймворка, не меняя его возможностей.
Пакет рендерера — пакет, который делегирует компоновку HTML или Office внешнему движку (Artisan/Cloudflare/Gotenberg), когда встроенный движок не справляется с задачей.
Form XObject — повторно используемый фрагмент содержимого PDF; Artisan импортирует отрисованную браузером страницу как один такой фрагмент, чтобы её текст оставался выделяемым.
NextPDF Connect — nextpdf/server, пакет, открывающий движок по MCP, REST и gRPC с детерминированной поверхностью исполнения.
Мягкая зависимость — модель Connect, в которой инструменты появляются автоматически по мере установки необязательных пакетов NextPDF, без изменения кода.