Integration cookbook
Integration cookbook
Section titled “Integration cookbook”NextPDF core renders Portable Document Format (PDF) 2.0 from PHP. The nine
integration packages connect that engine to a framework, a rendering backend,
a legacy codebase, a build pipeline, or a network service. This page explains
what each integration is for, lists its package name and core version
constraint (read directly from its composer.json), and links to the
per-integration recipes that appear here as source repositories ship their
docs/public/ trees.
This page is an index, so it makes no behavioral claim about any integration. Each integration’s repository owns its recipes. The aggregator pulls those recipes into this site. Until a recipe lands, its link points to a placeholder. For a use-case-driven recommendation, read Choose an integration. For the contract that every runnable recipe follows, read Recipe conventions.
The five integration shapes
Section titled “The five integration shapes”The nine packages fall into five shapes. Each shape tells you what kind of problem the integration solves.
- Framework integrations wire NextPDF into an application framework’s
service container and request lifecycle:
nextpdf/laravel,nextpdf/symfony,nextpdf/codeigniter. You install one, resolve a service, and return a PDF response. - Renderer bridges send the HTML-to-PDF or Office-to-PDF step to an
external rendering backend instead of the in-process pipeline:
nextpdf/artisan(headless Chrome over the Chrome DevTools Protocol),nextpdf/gotenberg(a Gotenberg microservice),nextpdf/cloudflare(Cloudflare Browser Rendering at the edge). - A compatibility shim lets a codebase written for a legacy PDF library
call NextPDF before you rewrite it:
nextpdf/compat-legacy. - A build tool produces a PHP 8.1 / 7.4 backport of NextPDF for runtimes
that cannot run 8.4:
nextpdf/backport-builder. - A network service exposes NextPDF over Representational State Transfer
(REST), gRPC, and the Model Context Protocol for AI systems and remote
callers:
nextpdf/server(distributed as NextPDF Connect).
The renderer bridges that speak Hypertext Transfer Protocol (HTTP)
(nextpdf/gotenberg, nextpdf/cloudflare, and the HTTP-client path in
nextpdf/laravel) depend on a PHP Standard Recommendation 18 (PSR-18) HTTP
client supplied by the host application. Under PSR-18 §4, the client raises a
typed client exception only when it cannot send the request at all. An HTTP
4xx or 5xx response is a normal return value, not an exception, under the
same clause PSR-18 §4. Recipes that call a remote renderer handle transport
errors and non-success statuses as separate cases.
Package and core-constraint reference
Section titled “Package and core-constraint reference”Every value below comes from the named package’s composer.json (the
authoritative source). The core constraint is the package’s declared
nextpdf/core requirement. nextpdf/backport-builder declares no
nextpdf/core requirement because it transforms the engine source instead of
depending on the engine at runtime.
| Integration | Package | Shape | Core constraint | Recipe |
|---|---|---|---|---|
| Laravel | nextpdf/laravel | Framework | ^3.0 || ^5.2 | Laravel quickstart [[/integrations/laravel/quickstart/]] |
| Symfony | nextpdf/symfony | Framework | ^3.0 || ^5.2 | Symfony quickstart [[/integrations/symfony/quickstart/]] |
| CodeIgniter 4 | nextpdf/codeigniter | Framework | ^3.0 || ^5.2 | CodeIgniter quickstart [[/integrations/codeigniter/quickstart/]] |
| Artisan (Chrome) | nextpdf/artisan | Renderer bridge | ^3.0 || ^5.2 | Artisan quickstart [[/integrations/artisan/quickstart/]] |
| Gotenberg | nextpdf/gotenberg | Renderer bridge | ^3.0 | Gotenberg quickstart [[/integrations/gotenberg/quickstart/]] |
| Cloudflare | nextpdf/cloudflare | Renderer bridge | ^3.0 | Cloudflare quickstart [[/integrations/cloudflare/quickstart/]] |
| Compat (legacy) | nextpdf/compat-legacy | Compatibility shim | ^3.0 | Compat-legacy quickstart [[/integrations/compat-legacy/quickstart/]] |
| Backport builder | nextpdf/backport-builder | Build tool | not applicable | Backport quickstart [[/integrations/backport/quickstart/]] |
| Connect (server) | nextpdf/server | Network service | ^3.0 | Connect quickstart [[/integrations/connect/quickstart/]] |
NextPDF distributes nextpdf/server under the product name NextPDF Connect;
its recipes live under the connect slug. nextpdf/compat-legacy ships from
the compat family; its recipes live under the compat-legacy slug.
Every package requires PHP >=8.4 <9.0 at its own runtime.
nextpdf/backport-builder exists to produce artifacts that run on PHP 8.1
(and a 7.4 target). The resulting backported engine, not the builder, runs on
the older runtime.
What each integration is for
Section titled “What each integration is for”Framework integrations
Section titled “Framework integrations”nextpdf/laravel— a Laravel 12 service provider, facade, and PDF response helpers. Use it when your application is a Laravel app and you want NextPDF resolved from the container and returned as an HTTP response without hand-wiring. Recipe: [[/integrations/laravel/quickstart/]].nextpdf/symfony— a Symfony 7 bundle with dependency-injection services and PDF response helpers. Use it when your application is a Symfony app. The bundle registers the engine as a service and integrates withsymfony/http-foundationresponses. Recipe: [[/integrations/symfony/quickstart/]].nextpdf/codeigniter— a CodeIgniter 4 service, library wrapper, and PDF response helpers. Use it when your application is a CodeIgniter 4 app and you want NextPDF available through the framework’s service locator. Recipe: [[/integrations/codeigniter/quickstart/]].
Renderer bridges
Section titled “Renderer bridges”nextpdf/artisan— a headless-Chrome renderer over the Chrome DevTools Protocol. Use it when a document needs a browser’s Cascading Style Sheets (CSS) engine for layout fidelity that the in-process HTML pipeline does not target, and you can run a Chrome process near the application. Recipe: [[/integrations/artisan/quickstart/]].nextpdf/gotenberg— Office-to-PDF and HTML-to-PDF conversion through a Gotenberg microservice. Use it when the input is an Office document, or when rendering must run out of process in a separate service. It speaks HTTP via a host-supplied PSR-18 client. Recipe: [[/integrations/gotenberg/quickstart/]].nextpdf/cloudflare— serverless rendering via the Cloudflare Browser Rendering API. Use it when rendering should run at the edge with no long-lived browser process to operate. It speaks HTTP via a host-supplied PSR-18 client. Recipe: [[/integrations/cloudflare/quickstart/]].
Compatibility shim
Section titled “Compatibility shim”nextpdf/compat-legacy— a compatibility layer for codebases written against a legacy PDF library. Use it to call NextPDF from existing code before you rewrite the call sites. It is a migration aid, not a permanent dependency. Recipe: [[/integrations/compat-legacy/quickstart/]].
Build tool
Section titled “Build tool”nextpdf/backport-builder— a Rector-based downgrade pipeline that produces a PHP 8.1 (and 7.4 target) build of NextPDF. Use it when a runtime cannot move to PHP 8.4 and you still need the engine there. It is build infrastructure, not an application’s runtime dependency. Recipe: [[/integrations/backport/quickstart/]].
Network service
Section titled “Network service”nextpdf/server(NextPDF Connect) — exposes NextPDF over a REST API, a gRPC service, and the Model Context Protocol. Use it when callers are remote, use another language, or are AI systems that need a tool endpoint instead of a PHP library. Recipe: [[/integrations/connect/quickstart/]].
How the recipe links resolve
Section titled “How the recipe links resolve”Each [[…]] placeholder above is a forward reference to a page authored in the
integration’s repository under docs/public/ and pulled into this site by the
aggregator. The target slugs follow one convention:
/integrations/<integration>/<recipe>/The <integration> token is the short name taken directly from the package
and core-constraint reference table above. Each row in that table supplies one
short name. The first recipe every integration ships is named quickstart;
later recipes use additional <recipe> segments under the same
<integration> root. Until a target page aggregates, its link is a placeholder
and does not resolve. This index makes no behavioral claim about any target
page. It records only the package facts verified from composer.json and the
slug each repository’s recipes will occupy.
See also
Section titled “See also”- Choose an integration — a decision matrix that maps use cases to integrations.
- Recipe conventions — the contract every runnable recipe in this cookbook follows.