Выбор интеграции

Используйте эту страницу, чтобы сопоставить свой сценарий с интеграцией, которая его поддерживает. Каждая рекомендация основана только на описании пакета в composer.json и его заявленном назначении; оба источника считаны напрямую из исходного репозитория. Когда две интеграции пересекаются по области применения, здесь указан различающий фактор, чтобы вы могли уверенно выбрать.

Найдите строку, соответствующую вашей ситуации, и начните с неё.

Начните отсюда: что у вас есть?

У вас есть …	Использовать	Почему (проверенное назначение)
Приложение на Laravel 12	`nextpdf/laravel`	Интеграция с фреймворком Laravel: поставщик служб, фасад и вспомогательные методы для ответов в формате Portable Document Format (PDF).
Приложение на Symfony 7	`nextpdf/symfony`	Пакет (bundle) для Symfony: службы для внедрения зависимостей (DI) и вспомогательные методы для ответов в формате PDF.
Приложение на CodeIgniter 4	`nextpdf/codeigniter`	Службы CodeIgniter 4, библиотека-обёртка и вспомогательные методы для ответов в формате PDF.
Приложение на PHP без фреймворка	`nextpdf/core` напрямую	Интеграция с фреймворком не нужна; движок — это обычная библиотека.
HTML, которому нужен браузерный движок Cascading Style Sheets (CSS), и вы можете запустить Chrome	`nextpdf/artisan`	Средство отрисовки на основе Chrome DevTools Protocol (CDP) для HTML, которому нужен браузерный макет CSS.
Документ Office для преобразования, например DOCX, XLSX или ODT	`nextpdf/gotenberg`	Преобразование Office в PDF через микросервис Gotenberg.
Нужна отрисовка без браузерного процесса в эксплуатации	`nextpdf/cloudflare`	Бессерверная отрисовка через Cloudflare Browser Rendering API на пограничных узлах.
Код, написанный под устаревшую библиотеку PDF	`nextpdf/compat-legacy`	Слой совместимости с устаревшей библиотекой PDF; позволяет вызывать NextPDF без переписывания мест вызова.
Среда выполнения, оставшаяся на PHP 8.1 / 7.4	`nextpdf/backport-builder`	Конвейер понижения версии на базе Rector, который собирает артефакт движка под 8.1 / 7.4.
Удалённая вызывающая сторона, другой язык или система искусственного интеллекта (AI)	`nextpdf/server`	NextPDF Connect: интерфейсы Representational State Transfer (REST), gRPC и Model Context Protocol для удалённого выполнения.

Когда подходят две интеграции

Отрисовка HTML в PDF: Artisan vs Gotenberg vs Cloudflare vs core

Все три моста отрисовки превращают разметку в PDF. Они различаются принципом работы, а не качеством. Используйте различие в эксплуатации как решающий фактор.

nextpdf/artisan управляет Chrome в headless-режиме через Chrome DevTools Protocol. Ему нужен процесс Chrome, доступный для приложения. Выбирайте его, когда вы можете поддерживать этот процесс в эксплуатации и документу нужен браузерный движок CSS.
nextpdf/gotenberg вызывает внешний микросервис Gotenberg по HTTP. Выбирайте его, когда отрисовку нужно изолировать в отдельной службе или когда на входе документ Office. Gotenberg — единственный из трёх, чьё заявленное назначение включает преобразование Office в PDF.
nextpdf/cloudflare вызывает Cloudflare Browser Rendering API. Выбирайте его, когда вам нужна edge/serverless-отрисовка без браузерного процесса, который пришлось бы запускать или обновлять.
Внутрипроцессному HTML-конвейеру ядра NextPDF ничего из перечисленного не нужно. Используйте мост отрисовки только тогда, когда внутрипроцессный конвейер не может обеспечить нужную для документа точность макета или изоляцию процесса. Мост намеренно делегирует этот шаг; это не путь по умолчанию.

Двум HTTP-мостам (nextpdf/gotenberg, nextpdf/cloudflare) нужен HTTP-клиент PSR-18, который предоставляет хост-приложение. В их рецептах транспортный сбой и неуспешный HTTP-статус рассматриваются как разные исходы.

Преобразование документа Office

nextpdf/gotenberg — это интеграция, в чьём проверенном описании из composer.json названо преобразование Office в PDF. Остальные мосты отрисовки описывают отрисовку HTML, а не ввод Office. Если исходный файл — DOCX/XLSX/ODT, используйте эту интеграцию.

Миграция с устаревшей библиотеки PDF

Согласно заявленному назначению, nextpdf/compat-legacy — это слой совместимости для кодовых баз, написанных под устаревшую библиотеку PDF. Он позволяет существующим местам вызова обращаться к NextPDF до того, как вы их перепишете. Рассматривайте его как вспомогательное средство миграции с запланированным удалением, а не как постоянную зависимость среды выполнения. Новый код должен вызывать nextpdf/core (или соответствующую интеграцию с фреймворком) напрямую.

Работа на PHP 8.1 или 7.4

Каждый пакет экосистемы объявляет PHP >=8.4 <9.0. nextpdf/backport-builder создан именно для этого ограничения: его заявленное назначение — конвейер понижения версии на базе Rector, который собирает артефакт для PHP 8.1+ (и сборку для 7.4). Это инструмент сборки, а не зависимость среды выполнения вашего приложения. Запустите сборщик, чтобы получить движок с обратным портированием, затем разверните этот движок.

Вызывающая сторона не на PHP или AI-агент

nextpdf/server (NextPDF Connect) предоставляет движок через REST API, службу gRPC и Model Context Protocol. Выбирайте его, когда вызывающая сторона удалённая, написана на другом языке или является системой AI, которая обращается к конечной точке инструмента, а не к библиотеке PHP. Приложению на PHP в том же процессе следует использовать nextpdf/core или интеграцию с фреймворком, а не вводить сетевой переход.

Совместное использование нескольких интеграций

Интеграция с фреймворком и мост отрисовки работают на разных уровнях, поэтому вы можете установить оба. Интеграция с фреймворком отвечает за подключение к контейнеру и HTTP-ответ; мост отрисовки отвечает за серверную часть отрисовки. При разрешении объединённого набора зависимостей проверьте, какие версии nextpdf/core принимает каждый пакет. Справочник по ограничениям ядра в индексе сборника рецептов по интеграциям — источник истины. Рецепты для отдельных сочетаний находятся в соответствующих репозиториях; ссылки на них есть в этом индексе.

См. также

Сборник рецептов по интеграциям — справочник по пакетам и ограничениям ядра, а также индекс ссылок на рецепты.
Соглашения по рецептам — контракт, которому следует каждый исполняемый рецепт.