The integration decision guide

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

At a glance

The NextPDF ecosystem is a small core engine plus a set of focused packages: framework bridges, two HTML renderers, an edge renderer, and an execution server. This page maps real use cases to the package that fits, based on what each package actually contains. The choice stays yours, grounded in evidence rather than implied by the documentation.

Why this matters

Picking the wrong integration is expensive in a way that does not show up right away. Choose a remote browser renderer when the in-process engine would have rendered the document correctly, and you add a network hop and an availability dependency to every PDF. Choose the in-process engine for a document that genuinely needs a full browser layout engine, and you get a file that is subtly wrong. The package you adopt shapes latency, failure modes, and operational surface, so the decision deserves to be explicit.

The short version

• Start with the core engine. Everything else is additive. If the in-process engine renders your document correctly, you need no renderer package at all.
• The framework bridge follows your framework, not your document. Laravel, Symfony, and CodeIgniter integrations exist so you get a facade or factory, a PDF response, queued generation, and auto-discovery — they do not change what the engine can render.
• Use a renderer only when CSS fidelity requires a browser. Artisan (local Chrome) and Cloudflare (edge browser) exist for exactly that; Gotenberg exists to bring Office documents in.
• Use Connect when the caller is a service or an AI agent, not a PHP call. It exposes the engine over MCP, REST, and gRPC with a human-approval gate for dangerous operations.

How NextPDF approaches it

The ecosystem is intentionally layered so each package has one job. The core engine renders PDF in-process. A framework bridge adapts that engine to a framework’s idioms. A renderer package delegates HTML or Office layout to an external engine when the in-process one is not the right tool. Connect turns the engine into a network service. None of these packages overlaps another’s responsibility, which is what makes the decision tractable. You are not choosing between competing tools. You are composing complementary ones.

Make the decision against the use case. The table maps each scenario to the package that fits and states the trade you accept.

Use case	Package that fits	What it actually provides	The trade you accept
PDF in a Laravel app	nextpdf/laravel	Auto-discovered service provider, Pdf facade, PdfResponse (inline/download/streamed, OWASP headers), a queued GeneratePdfJob with tries/timeout/backoff, Octane-safe locked registries	A Laravel 12 dependency; the engine’s capabilities are unchanged
PDF in a Symfony app	nextpdf/symfony	Auto-registered bundle, injectable PdfFactory, PdfResponse, an optional Messenger handler for async generation	A Symfony 7.2 bundle dependency; capabilities unchanged
PDF in a CodeIgniter 4 app	nextpdf/codeigniter	service('pdf') / pdf() helper, a Pdf library wrapping a disposable Document, a PdfResponse, an optional queued job	A CodeIgniter 4.6 dependency; capabilities unchanged
Document needs full browser CSS (flex/grid/web fonts) in-process-adjacent	nextpdf/artisan	Headless Chrome via CDP, rendered then imported back as a Form XObject so text stays selectable; a browser pool	A Chrome runtime and its memory/process cost on your host
Office documents (.docx, .xlsx) to PDF	nextpdf/gotenberg	A PSR-18 bridge to a Gotenberg microservice with SSRF-hardened, IP-pinned transport	An external Gotenberg service and a network dependency
HTML→PDF at the edge / no local Chrome	nextpdf/cloudflare	Cloudflare Browser Rendering via pinned transport, with optional local-Chrome fallback	A Cloudflare account and a network dependency; fallback needs Artisan
Engine consumed by a service or AI agent	nextpdf/server (Connect)	One engine over MCP (stdio), REST (OpenAPI 3.1), and gRPC; soft-dependency tool discovery; a human-confirmation gate for high-risk tools	Operating a service surface; deterministic-execution discipline

Human-factors note: Human-factors note

These are two independent decisions, and people often combine them. The framework bridge is chosen by the framework you already use — it does not expand or restrict what the engine renders. The renderer is chosen by the document. The deciding question is whether the in-process CSS engine is enough, or whether the document genuinely needs a browser layout engine. You can need a framework bridge and no renderer, a renderer and no bridge, both, or neither. Treating them as one question is the most common integration mistake, which is why this page separates them.

What the evidence says

This page is editorial — a routing decision — but the routing is grounded in what each package’s manifest and main classes contain.

Evidence ¶ Editorial Evidence: Editorial

The bridges are real and parallel. Each declares its framework dependency and auto-registration in its composer.json (extra.laravel.providers, extra.symfony.bundles, the CodeIgniter Registrar). Each also ships a PdfResponse, a disposable-document binding, and an optional queued job. None of them adds a rendering capability — they adapt the same engine. The renderers are real and distinct. Artisan depends on chrome-php/chrome and imports the Chrome PDF back as a Form XObject to keep text selectable. Gotenberg and Cloudflare are PSR-18 HTTP bridges with explicitly SSRF-hardened, IP-pinned transports. Cloudflare can fall back to Artisan when the Worker is unreachable. Connect’s composer.json declares the three transports and a soft-dependency model in which tools appear as their packages are installed, governed by a four-level risk model with a human-confirmation gate.

The way this page routes you is standard-backed in form: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 says readers should be able to quickly determine whether content serves their purpose, and Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 requires links and references to state their destination — which is why the table names the concrete package and the trade rather than vaguely referring to “an integration”.

Practical example

The decision is a sequence of honest questions, not a feature comparison. The following flow resolves the common cases.

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.

The structure is the lesson: rendering and invocation are separate axes. Answering them together is how teams end up with a remote renderer they did not need, or a bridge that does not solve their fidelity problem.

Common misconception

The dominant misconception is “I need a renderer package to generate PDFs.” You do not. The core engine generates PDF in-process. Renderer packages exist only for the specific case where a browser-grade layout engine is required or the source is an Office document. When the in-process engine already produces the correct file, adopting a renderer reflexively adds a runtime dependency and a failure mode for no benefit.

The mirror-image misconception is “the framework bridge unlocks capabilities.” It does not. A bridge changes how you call the engine — facade, factory, response, queued job — not what it can produce. Signing, PDF/A, and structured invoices are tier and engine concerns, identical whether you call through a bridge or directly.

Limits and boundaries

• This page routes; it does not benchmark or rank. It states what each package provides and the trade. Choosing among them is your decision on your constraints.
• Package capabilities are read from their manifests and main classes at a point in time. Treat each package’s own documentation as authoritative for its current API. This guide is the map, not the spec.
• No competitor comparison is offered or implied. The only subject is the NextPDF ecosystem and how its parts fit together.
• The framework bridge and the renderer are independent choices. A bridge does not expand engine capability; a renderer does not depend on a framework.
• External renderers add an availability dependency. Gotenberg and Cloudflare introduce a network call and a service to operate; that is the accepted trade, not a hidden cost.
• Tier-gated capabilities are orthogonal to integration. Commercial features are unlocked by the tier, not by any bridge or renderer; see the boundary below.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Every integration package (bridges, Artisan, Gotenberg, Cloudflare, Connect) works against Core and is Apache-2.0. They adapt or expose the engine; they do not gate features.
Pro	○ Commercial capabilities (PAdES baseline signing, PDF/A, advanced barcodes) are unlocked by the tier and are then available through any integration, not by switching integration.
Enterprise	○ Structured invoices, validation policies, and the Connect human-confirmation gate for high-risk tools are tier capabilities, likewise integration-independent.

Related docs

• The HTML pipeline — what the in-process CSS engine covers, so you know when a browser renderer is actually needed.
• When not to use NextPDF — the honest boundary on document problems the engine is not the right tool for.
• The PHP 8.4 foundations — the runtime floor every package shares and what the backport path preserves.

Glossary

• Core engine — nextpdf/core, the in-process PDF 2.0 engine every other package builds on.
• Framework bridge — an integration package (Laravel/Symfony/CodeIgniter) that adapts the engine to a framework’s idioms without changing its capabilities.
• Renderer package — a package that delegates HTML or Office layout to an external engine (Artisan/Cloudflare/Gotenberg) when the in-process engine is not the right tool.
• Form XObject — a reusable PDF content fragment; Artisan imports a browser-rendered page as one so its text remains selectable.
• NextPDF Connect — nextpdf/server, the package exposing the engine over MCP, REST, and gRPC with a deterministic execution surface.
• Soft dependency — Connect’s model where tools appear automatically as optional NextPDF packages are installed, with no code change.