Сборник рецептов по интеграциям

Ядро NextPDF создаёт Portable Document Format (PDF) 2.0 из PHP. Девять интеграционных пакетов связывают этот движок с фреймворком, бэкендом отрисовки, унаследованной кодовой базой, конвейером сборки или сетевым сервисом. На этой странице объясняется назначение каждой интеграции, указаны имя её пакета и ограничение версии ядра (взятые напрямую из её composer.json), а также даны ссылки на рецепты по каждой интеграции, которые появляются здесь по мере публикации деревьев docs/public/ в исходных репозиториях.

Эта страница служит указателем, поэтому не утверждает ничего о поведении какой-либо интеграции. Рецепты каждой интеграции принадлежат её репозиторию, а агрегатор подтягивает их на этот сайт. Пока рецепт не появился, ссылка на него ведёт на заполнитель. Чтобы подобрать интеграцию под ваш сценарий, прочитайте Выбор интеграции. Чтобы узнать контракт, которому должен следовать каждый исполняемый рецепт, прочитайте Соглашения по рецептам.

Пять видов интеграций

Девять пакетов делятся на пять видов. Вид показывает, какую задачу решает интеграция.

Интеграции с фреймворками встраивают NextPDF в контейнер сервисов и жизненный цикл запроса прикладного фреймворка: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Вы устанавливаете одну из них, получаете сервис и возвращаете ответ в формате PDF.
Мосты к движкам отрисовки передают преобразование HTML в PDF или Office в PDF внешнему бэкенду отрисовки, а не внутрипроцессному конвейеру: nextpdf/artisan (headless-Chrome через Chrome DevTools Protocol), nextpdf/gotenberg (микросервис Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering на периферии).
Слой совместимости позволяет кодовой базе, написанной для унаследованной библиотеки PDF, вызывать NextPDF до её переписывания: nextpdf/compat-legacy.
Инструмент сборки создаёт бэкпорт NextPDF для PHP 8.1 / 7.4, предназначенный для сред выполнения, где нельзя использовать 8.4: nextpdf/backport-builder.
Сетевой сервис предоставляет NextPDF через Representational State Transfer (REST), gRPC и Model Context Protocol для систем ИИ и удалённых клиентов: nextpdf/server (распространяется как NextPDF Connect).

Мосты к движкам отрисовки, работающие по Hypertext Transfer Protocol (HTTP) (nextpdf/gotenberg, nextpdf/cloudflare и путь через HTTP-клиент в nextpdf/laravel), используют HTTP-клиент стандарта PHP Standard Recommendation 18 (PSR-18), который предоставляет хост-приложение. Согласно PSR-18 §4, клиент выбрасывает типизированное клиентское исключение только тогда, когда вообще не может отправить запрос. HTTP-ответ 4xx или 5xx возвращается как обычный результат, а не как исключение, согласно тому же пункту PSR-18 §4. Рецепты, обращающиеся к удалённому движку отрисовки, обрабатывают ошибки транспорта и неуспешные HTTP-статусы как отдельные случаи.

Справочник по пакетам и ограничениям версии ядра

Каждое значение ниже взято из composer.json указанного пакета (канонический источник). Ограничение версии ядра — это объявленное пакетом требование к nextpdf/core. nextpdf/backport-builder не объявляет требования к nextpdf/core, поскольку преобразует исходный код движка, а не зависит от него во время выполнения.

Интеграция	Пакет	Вид	Ограничение версии ядра	Рецепт
Laravel	`nextpdf/laravel`	фреймворк	`^3.0 \|\| ^5.2`	Быстрый старт Laravel [[/integrations/laravel/quickstart/]]
Symfony	`nextpdf/symfony`	фреймворк	`^3.0 \|\| ^5.2`	Быстрый старт Symfony [[/integrations/symfony/quickstart/]]
CodeIgniter 4	`nextpdf/codeigniter`	фреймворк	`^3.0 \|\| ^5.2`	Быстрый старт CodeIgniter [[/integrations/codeigniter/quickstart/]]
Artisan (браузер Chrome)	`nextpdf/artisan`	Мост к движку отрисовки	`^3.0 \|\| ^5.2`	Быстрый старт Artisan [[/integrations/artisan/quickstart/]]
Gotenberg	`nextpdf/gotenberg`	Мост к движку отрисовки	`^3.0`	Быстрый старт Gotenberg [[/integrations/gotenberg/quickstart/]]
Cloudflare	`nextpdf/cloudflare`	Мост к движку отрисовки	`^3.0`	Быстрый старт Cloudflare [[/integrations/cloudflare/quickstart/]]
Compat (унаследованный)	`nextpdf/compat-legacy`	Слой совместимости	`^3.0`	Быстрый старт Compat-legacy [[/integrations/compat-legacy/quickstart/]]
Сборщик бэкпортов	`nextpdf/backport-builder`	Инструмент сборки	неприменимо	Быстрый старт Backport [[/integrations/backport/quickstart/]]
Connect (сервер)	`nextpdf/server`	Сетевой сервис	`^3.0`	Быстрый старт Connect [[/integrations/connect/quickstart/]]

NextPDF распространяет nextpdf/server под продуктовым названием NextPDF Connect; его рецепты размещаются под слагом connect. nextpdf/compat-legacy поставляется из семейства compat; его рецепты размещаются под слагом compat-legacy.

Для собственной среды выполнения каждый пакет требует PHP >=8.4 <9.0. nextpdf/backport-builder существует для создания артефактов, работающих на PHP 8.1 (а также с целевой версией 7.4). В более старой среде выполнения запускается получившийся бэкпортированный движок, а не сборщик.

Для чего предназначена каждая интеграция

Интеграции с фреймворками

nextpdf/laravel — поставщик сервиса, фасад и помощники для PDF-ответов в Laravel 12. Используйте её, когда ваше приложение написано на Laravel и вы хотите получать NextPDF из контейнера и возвращать его как HTTP-ответ без ручной настройки. Рецепт: [[/integrations/laravel/quickstart/]].
nextpdf/symfony — бандл для Symfony 7 с сервисами внедрения зависимостей и помощниками для PDF-ответов. Используйте его, когда ваше приложение написано на Symfony. Бандл регистрирует движок как сервис и интегрируется с ответами symfony/http-foundation. Рецепт: [[/integrations/symfony/quickstart/]].
nextpdf/codeigniter — сервис, библиотека-обёртка и помощники для PDF-ответов в CodeIgniter 4. Используйте его, когда ваше приложение написано на CodeIgniter 4 и вы хотите, чтобы NextPDF был доступен через локатор сервисов фреймворка. Рецепт: [[/integrations/codeigniter/quickstart/]].

Мосты к движкам отрисовки

nextpdf/artisan — движок отрисовки на основе headless-Chrome через Chrome DevTools Protocol. Используйте его, когда документу нужен браузерный движок Cascading Style Sheets (CSS) для точности макета, которую не обеспечивает внутрипроцессный HTML-конвейер, и вы можете запустить процесс Chrome рядом с приложением. Рецепт: [[/integrations/artisan/quickstart/]].
nextpdf/gotenberg — преобразование Office в PDF и HTML в PDF через микросервис Gotenberg. Используйте его, когда на вход поступает документ Office или когда отрисовка должна выполняться вне процесса в отдельном сервисе. Он работает по HTTP через клиент PSR-18, который предоставляет хост-приложение. Рецепт: [[/integrations/gotenberg/quickstart/]].
nextpdf/cloudflare — бессерверная отрисовка через API Cloudflare Browser Rendering. Используйте его, когда отрисовка должна выполняться на периферии без необходимости поддерживать постоянно работающий процесс браузера. Он работает по HTTP через клиент PSR-18, который предоставляет хост-приложение. Рецепт: [[/integrations/cloudflare/quickstart/]].

Слой совместимости

nextpdf/compat-legacy — слой совместимости для кодовых баз, написанных под унаследованную библиотеку PDF. Используйте его, чтобы вызывать NextPDF из существующего кода до переписывания мест вызова. Это вспомогательное средство для миграции, а не постоянная зависимость. Рецепт: [[/integrations/compat-legacy/quickstart/]].

Инструмент сборки

nextpdf/backport-builder — конвейер понижения версии на основе Rector, который создаёт сборку NextPDF для PHP 8.1 (с целевой версией 7.4). Используйте его, когда среду выполнения нельзя перевести на PHP 8.4, но в ней всё равно нужен движок. Это инфраструктура сборки, а не зависимость приложения во время выполнения. Рецепт: [[/integrations/backport/quickstart/]].

Сетевой сервис

nextpdf/server (NextPDF Connect) — предоставляет NextPDF через REST API, сервис gRPC и Model Context Protocol. Используйте его, когда вызывающие стороны находятся удалённо, используют другой язык или являются системами ИИ, которым нужна конечная точка инструмента, а не библиотека PHP. Рецепт: [[/integrations/connect/quickstart/]].

Как разрешаются ссылки на рецепты

Каждый заполнитель [[…]] выше — это предварительная ссылка на страницу, созданную в репозитории интеграции в docs/public/ и подтягиваемую на этот сайт агрегатором. Целевые слаги следуют единому соглашению:

/integrations/<integration>/<recipe>/

Токен <integration> — это короткое имя, взятое напрямую из приведённой выше таблицы со справочником по пакетам и ограничениям версии ядра. В каждой строке этой таблицы указано одно короткое имя. Первый рецепт, который поставляет каждая интеграция, называется quickstart; в последующих рецептах используются дополнительные сегменты <recipe> под тем же корнем <integration>. Пока целевая страница не агрегирована, ссылка остаётся заполнителем и не разрешается. Этот указатель не утверждает ничего о поведении какой-либо целевой страницы. Он фиксирует только факты о пакете, проверенные по composer.json, и слаг, который будут использовать рецепты каждого репозитория.

См. также

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