통합 의사결정 가이드

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

한눈에 보기

NextPDF 생태계는 작은 코어 엔진에 목적이 분명한 일련의 패키지가 더해진 형태입니다. 프레임워크 브리지, 두 개의 HTML 렌더러, 엣지 렌더러, 그리고 실행 서버로 구성됩니다. 이 페이지는 각 패키지가 실제로 무엇을 담고 있는지를 바탕으로, 실제 유스케이스를 그에 맞는 패키지에 대응시킵니다. 선택은 여러분의 몫으로 남으며, 문서가 암시하는 대로가 아니라 근거에 기반합니다.

왜 중요한가

잘못된 통합을 고르면 곧바로 드러나지 않는 방식으로 비용이 듭니다. 인프로세스 엔진이 문서를 올바르게 렌더링했을 상황에서 원격 브라우저 렌더러를 고르면, 모든 PDF에 네트워크 홉과 가용성 의존성을 더하게 됩니다. 완전한 브라우저 레이아웃 엔진이 정말로 필요한 문서에 인프로세스 엔진을 고르면, 미묘하게 어긋난 파일을 얻게 됩니다. 채택하는 패키지는 지연 시간, 실패 모드, 운영 면을 좌우하므로, 이 결정은 명시적으로 내릴 가치가 있습니다.

짧게 요약하면

코어 엔진에서 시작하십시오. 그 밖의 모든 것은 부가적입니다. 인프로세스 엔진이 문서를 올바르게 렌더링한다면, 렌더러 패키지는 전혀 필요하지 않습니다.
프레임워크 브리지는 문서가 아니라 여러분의 프레임워크를 따릅니다. Laravel, Symfony, CodeIgniter 통합은 파사드 또는 팩토리, PDF 응답, 큐 기반 생성, 자동 발견을 제공하기 위해 존재합니다. 엔진이 렌더링할 수 있는 범위를 바꾸지는 않습니다.
CSS 충실도가 브라우저를 요구할 때에만 렌더러를 사용하십시오. Artisan(로컬 Chrome)과 Cloudflare(엣지 브라우저)는 바로 그 용도로 존재합니다. Gotenberg는 Office 문서를 가져오기 위해 존재합니다.
호출자가 PHP 호출이 아니라 서비스나 AI 에이전트일 때 Connect를 사용하십시오. Connect는 엔진을 MCP, REST, gRPC로 노출하며, 위험한 작업에는 사람의 승인 게이트를 둡니다.

NextPDF가 접근하는 방식

이 생태계는 각 패키지가 하나의 역할을 맡도록 의도적으로 계층화되어 있습니다. 코어 엔진은 PDF를 인프로세스로 렌더링합니다. 프레임워크 브리지는 그 엔진을 프레임워크의 관용구에 맞춥니다. 렌더러 패키지는 인프로세스 엔진이 적절한 도구가 아닐 때 HTML 또는 Office 레이아웃을 외부 엔진에 위임합니다. Connect는 엔진을 네트워크 서비스로 바꿉니다. 이 패키지들 중 어느 것도 서로의 책임을 겹치지 않으며, 바로 그 점이 결정을 다루기 쉽게 만듭니다. 여러분은 경쟁하는 도구 중에서 고르는 것이 아닙니다. 서로를 보완하는 도구들을 조합하는 것입니다.

결정은 유스케이스에 비추어 내리십시오. 아래 표는 각 시나리오를 그에 맞는 패키지에 대응시키고, 여러분이 받아들이는 트레이드오프를 명시합니다.

유스케이스	적합한 패키지	실제로 제공하는 것	받아들이는 트레이드오프
Laravel 앱에서의 PDF	`nextpdf/laravel`	자동 발견되는 서비스 프로바이더, `Pdf` 파사드, `PdfResponse`(인라인/다운로드/스트리밍, OWASP 헤더), tries/timeout/backoff를 갖춘 큐 기반 `GeneratePdfJob`, Octane 안전 잠금 레지스트리	Laravel 12 의존성. 엔진의 기능은 그대로
Symfony 앱에서의 PDF	`nextpdf/symfony`	자동 등록되는 번들, 주입 가능한 `PdfFactory`, `PdfResponse`, 비동기 생성을 위한 선택적 Messenger 핸들러	Symfony 7.2 번들 의존성. 기능은 그대로
CodeIgniter 4 앱에서의 PDF	`nextpdf/codeigniter`	`service('pdf')` / `pdf()` 헬퍼, 일회용 `Document`를 감싸는 `Pdf` 라이브러리, `PdfResponse`, 선택적 큐 기반 작업	CodeIgniter 4.6 의존성. 기능은 그대로
문서가 인프로세스에 인접한 형태로 완전한 브라우저 CSS(flex/grid/웹 폰트)를 필요로 함	`nextpdf/artisan`	CDP를 통한 헤드리스 Chrome. 렌더링한 뒤 텍스트가 선택 가능하도록 Form XObject로 다시 가져옴. 브라우저 풀 포함	호스트에서의 Chrome 런타임과 그 memory/process 비용
Office 문서(`.docx`, `.xlsx`)를 PDF로	`nextpdf/gotenberg`	SSRF 강화 및 IP 고정 트랜스포트를 갖춘, Gotenberg 마이크로서비스로의 PSR-18 브리지	외부 Gotenberg 서비스와 네트워크 의존성
엣지에서의 HTML→PDF / 로컬 Chrome 없음	`nextpdf/cloudflare`	고정 트랜스포트를 통한 Cloudflare Browser Rendering. 선택적 로컬 Chrome 폴백 포함	Cloudflare 계정과 네트워크 의존성. 폴백에는 Artisan 필요
서비스 또는 AI 에이전트가 사용하는 엔진	`nextpdf/server`(Connect)	MCP(stdio), REST(OpenAPI 3.1), gRPC로 노출되는 단일 엔진. 소프트 의존성 기반 도구 발견. 고위험 도구에는 사람의 확인 게이트	서비스 면의 운영, 결정론적 실행 규율

이것은 두 개의 독립적인 결정이며, 사람들은 종종 둘을 한데 묶습니다. 프레임워크 브리지는 이미 사용하고 있는 프레임워크에 의해 정해집니다. 이것은 엔진이 렌더링하는 범위를 넓히거나 좁히지 않습니다. 렌더러는 문서에 의해 정해집니다. 결정적인 질문은 인프로세스 CSS 엔진으로 충분한가, 아니면 문서가 정말로 브라우저 레이아웃 엔진을 필요로 하는가입니다. 프레임워크 브리지는 필요하지만 렌더러는 필요 없을 수도, 렌더러는 필요하지만 브리지는 필요 없을 수도, 둘 다 필요할 수도, 아무것도 필요 없을 수도 있습니다. 이 둘을 하나의 질문으로 다루는 것이 가장 흔한 통합 실수이며, 그래서 이 페이지에서는 둘을 분리해 다룹니다.

증거가 말하는 것

이 페이지는 **편집적(editorial)**인 내용, 즉 라우팅 결정입니다. 다만 그 라우팅은 각 패키지의 매니페스트와 주요 클래스가 실제로 담고 있는 내용에 근거합니다.

이 브리지들은 실재하며 서로 평행한 구조를 갖습니다. 각 브리지는 프레임워크 의존성과 자동 등록을 자신의 composer.json(extra.laravel.providers, extra.symfony.bundles, CodeIgniter의 Registrar)에 선언합니다. 또한 각각 PdfResponse, 일회용 문서 바인딩, 선택적 큐 기반 작업을 함께 제공합니다. 이들 중 어느 것도 렌더링 기능을 추가하지 않습니다. 같은 엔진을 적응시킬 뿐입니다. 이 렌더러들은 실재하며 서로 구별됩니다. Artisan은 chrome-php/chrome에 의존하며, 텍스트가 선택 가능하도록 Chrome PDF를 Form XObject로 다시 가져옵니다. Gotenberg와 Cloudflare는 명시적으로 SSRF를 강화하고 IP를 고정한 트랜스포트를 갖춘 PSR-18 HTTP 브리지입니다. Cloudflare는 Worker에 도달할 수 없을 때 Artisan으로 폴백할 수 있습니다. Connect의 composer.json은 세 가지 트랜스포트와, 해당 패키지가 설치됨에 따라 도구가 나타나는 소프트 의존성 모델을 선언합니다. 이는 사람의 확인 게이트를 갖춘 4단계 위험 모델로 관리됩니다.

이 페이지가 여러분을 안내하는 방식은 형식 면에서 표준에 뒷받침되어 있습니다. Spec: ISO 24495-1:2023, §5 는 독자가 콘텐츠가 자신의 목적에 부합하는지를 빠르게 판단할 수 있어야 한다고 말하며, Spec: ISO/IEC/IEEE 26514:2022, §3.x222 는 링크와 참조가 그 목적지를 명시할 것을 요구합니다. 그래서 이 표는 “어떤 통합”이라고 막연하게 가리키는 대신, 구체적인 패키지와 트레이드오프를 명시합니다.

실용적인 예제

이 결정은 기능 비교가 아니라 정직한 질문의 연속입니다. 아래 흐름은 흔한 경우들을 정리합니다.

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.

이 구조 자체가 교훈입니다. 렌더링과 호출은 별개의 축입니다. 둘을 함께 답하려 하면 팀은 필요하지도 않았던 원격 렌더러를, 또는 충실도 문제를 해결하지 못하는 브리지를 떠안게 됩니다.

흔한 오해

가장 큰 오해는 *“PDF를 생성하려면 렌더러 패키지가 필요하다”*는 것입니다. 그렇지 않습니다. 코어 엔진은 PDF를 인프로세스로 생성합니다. 렌더러 패키지는 브라우저 수준의 레이아웃 엔진이 필요하거나 소스가 Office 문서인 특정 경우에만 존재합니다. 인프로세스 엔진이 이미 올바른 파일을 만들어 내고 있을 때 반사적으로 렌더러를 채택하면, 아무런 이득 없이 런타임 의존성과 실패 모드만 더하게 됩니다.

그 반대편의 오해는 *“프레임워크 브리지가 기능을 해금한다”*는 것입니다. 그렇지 않습니다. 브리지가 바꾸는 것은 엔진을 호출하는 방식(파사드, 팩토리, 응답, 큐 기반 작업)이지, 엔진이 생성할 수 있는 범위가 아닙니다. 서명, PDF/A, 구조화된 인보이스는 티어와 엔진의 영역이며, 브리지를 통해 호출하든 직접 호출하든 동일합니다.

한계와 경계

이 페이지는 라우팅을 제시하며, 벤치마크나 순위를 매기지 않습니다. 각 패키지가 제공하는 것과 트레이드오프를 명시할 뿐입니다. 그 가운데에서 고르는 일은 여러분의 제약 조건에 따른 여러분의 결정입니다.
패키지 기능은 특정 시점의 매니페스트와 주요 클래스에서 읽어 낸 것입니다. 현재 API에 대해서는 각 패키지 자체의 문서를 권위 있는 출처로 삼으십시오. 이 가이드는 지도이지 명세가 아닙니다.
경쟁 제품과의 비교는 제시하지도 암시하지도 않습니다. 유일한 대상은 NextPDF 생태계와 그 구성 요소들이 어떻게 맞물리는가입니다.
프레임워크 브리지와 렌더러는 독립적인 선택입니다. 브리지는 엔진 기능을 확장하지 않으며, 렌더러는 프레임워크에 의존하지 않습니다.
외부 렌더러는 가용성 의존성을 더합니다. Gotenberg와 Cloudflare는 네트워크 호출과 운영할 서비스를 도입합니다. 그것은 받아들인 트레이드오프이지 숨겨진 비용이 아닙니다.
티어로 제어되는 기능은 통합과 직교합니다. 상용 기능을 해금하는 것은 티어이지 어떤 브리지나 렌더러가 아닙니다. 아래 경계를 참조하십시오.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	모든 통합 패키지(브리지, Artisan, Gotenberg, Cloudflare, Connect)는 Core에 대해 동작하며 Apache-2.0입니다. 이들은 엔진을 적응시키거나 노출할 뿐, 기능을 게이팅하지 않습니다.
Pro	상용 기능(PAdES 기준 서명, PDF/A, 고급 바코드)은 티어에 의해 해금되며, 그 후에는 통합을 전환하는 것이 아니라 어떤 통합을 통해서든 사용할 수 있게 됩니다.
Enterprise	구조화된 인보이스, 검증 정책, 그리고 고위험 도구에 대한 Connect의 사람 확인 게이트는 티어 기능이며, 마찬가지로 통합과 무관합니다.

용어집

코어 엔진 — nextpdf/core. 다른 모든 패키지가 그 위에 세워지는, 인프로세스 PDF 2.0 엔진입니다.
프레임워크 브리지 — 엔진의 기능을 바꾸지 않으면서 엔진을 프레임워크의 관용구에 맞추는 통합 패키지(Laravel/Symfony/CodeIgniter)입니다.
렌더러 패키지 — 인프로세스 엔진이 적절한 도구가 아닐 때 HTML 또는 Office 레이아웃을 외부 엔진(Artisan/Cloudflare/Gotenberg)에 위임하는 패키지입니다.
Form XObject — 재사용 가능한 PDF 콘텐츠 조각입니다. Artisan은 텍스트가 선택 가능하도록 브라우저로 렌더링한 페이지를 이것으로 가져옵니다.
NextPDF Connect — nextpdf/server. 결정론적 실행 면을 갖추고 엔진을 MCP, REST, gRPC로 노출하는 패키지입니다.
소프트 의존성 — 선택적 NextPDF 패키지가 설치됨에 따라 코드 변경 없이 도구가 자동으로 나타나는 Connect의 모델입니다.