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

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

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

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

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

Интеграции с фреймворками встраивают 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
Symfony	`nextpdf/symfony`	фреймворк	`^3.0 \|\| ^5.2`	Быстрый старт Symfony
CodeIgniter 4	`nextpdf/codeigniter`	фреймворк	`^3.0 \|\| ^5.2`	Быстрый старт CodeIgniter
Artisan (браузер Chrome)	`nextpdf/artisan`	Мост к движку отрисовки	`^3.0 \|\| ^5.2`	Быстрый старт Artisan
Gotenberg	`nextpdf/gotenberg`	Мост к движку отрисовки	`^3.0`	Быстрый старт Gotenberg
Cloudflare	`nextpdf/cloudflare`	Мост к движку отрисовки	`^3.0`	Быстрый старт Cloudflare
Compat (унаследованный)	`nextpdf/compat-legacy`	Слой совместимости	`^3.0`	Быстрый старт TCPDF-compat
Сборщик бэкпортов	`nextpdf/backport-builder`	Инструмент сборки	неприменимо	Быстрый старт Backport
Connect (сервер)	`nextpdf/server`	Сетевой сервис	`^3.0`	Быстрый старт Connect

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

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

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

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

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

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

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

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

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

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

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

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

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

Как организованы слаги рецептов

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

См. также

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