경로 선택하기

한눈에 보기

NextPDF는 여러 진입 방식을 제공합니다. 적절한 선택은 코드가 실행되는 위치와 필요한 출력의 종류에 따라 달라집니다. 이 페이지에서는 세 가지 결정을 정리합니다. 어떤 배포판을 설치할지, 어떤 HTML 렌더러를 사용할지, 그리고 워크로드에 Pro 또는 Enterprise 티어가 필요한 시점입니다.

궁금한 점에 해당하는 섹션을 읽거나, 마지막에 있는 의사 결정 요약을 훑어보세요.

배포판 선택하기

애플리케이션이 엔진을 호출하는 방식부터 보세요. 상황에 맞는 첫 번째 행이 답입니다.

상황	설치	이유
일반 PHP 프로젝트, 라이브러리 또는 CLI 도구	NextPDF 코어 (nextpdf/core)	엔진만 제공합니다. 프레임워크를 전제하지 않으며 어떤 서비스도 실행하지 않습니다.
Laravel, Symfony 또는 CodeIgniter 애플리케이션	해당 프레임워크 통합	코어 위에 컨테이너 바인딩, 응답 헬퍼, 큐 작업을 추가로 제공합니다.
네트워크를 통해 엔진을 호출해야 하는 비 PHP 서비스, 에이전트 또는 기타 런타임	NextPDF Server (nextpdf/server)	단일 서비스가 MCP, REST, gRPC를 통해 엔진을 노출합니다.
NextPDF Server에서 PDF를 받아야 하는 Python 코드	Python SDK (pip install nextpdf) 클라이언트	실행 중인 서버용 타입 지정 클라이언트입니다. 엔진을 내장하지 않습니다.

다음 두 가지를 자주 혼동합니다.

• 프레임워크 통합은 코어를 포함합니다. 둘을 따로 설치하지 않습니다. 어댑터가 nextpdf/core를 대신 선언하고 해석합니다.
• Python SDK는 엔진이 아니라 클라이언트입니다. 통신할 NextPDF Server 엔드포인트가 필요합니다. PDF 생성은 서버 측 PHP에서 이루어집니다.

라이브러리인가, 서비스인가?

PHP 애플리케이션이 라이브러리를 직접 연결할 수 있다면 코어 또는 프레임워크 통합을 선호하세요. 실행해야 할 프로세스가 하나 줄고, 지연 시간이 가장 낮습니다. PHP가 아닌 구성 요소에서 엔진이 필요하거나, 여러 호출자가 공유하는 단일 렌더링 서비스를 원할 때 서버를 선택하세요.

HTML 렌더러 선택하기

NextPDF는 네 가지 방식으로 HTML을 PDF로 렌더링합니다. 내장 파이프라인은 추가 설정 없이 대부분의 문서를 처리합니다. 세 가지 렌더러 패키지는 브라우저 수준 레이아웃이 필요하거나 기존 서비스를 활용하려는 경우에 사용합니다.

렌더러	패키지	실행 위치	선택 기준
내장 writeHtml()	nextpdf/core	인프로세스, 순수 PHP	브라우저나 네트워크 호출 없이 지원되는 HTML 및 CSS 하위 집합을 원할 때입니다.
Artisan	nextpdf/artisan	호스트의 헤드리스 Chrome	텍스트 선택이 가능한 완전한 Chrome 레이아웃(flexbox, grid, 복잡한 선택자, 웹 글꼴)이 필요할 때입니다.
Cloudflare	nextpdf/cloudflare	엣지의 Cloudflare Browser Rendering	렌더링을 엣지에서 수행해야 하거나, 자체 호스트에서 브라우저 프로세스를 배제하려는 경우입니다.
Gotenberg	nextpdf/gotenberg	직접 운영하는 Gotenberg 서비스	기존 Gotenberg 배포를 통해 오피스 문서(DOCX, XLSX)나 HTML을 변환할 때입니다.

표를 읽는 방법:

• 무엇보다 먼저 내장 파이프라인을 선택하세요. 가장 빠른 경로이며 외부 의존성이 없습니다. 특정 속성에 의존하기 전에 CSS 지원 매트릭스에서 확인하세요.
• 레이아웃이 지원 하위 집합을 넘어가고 렌더링을 자체 인프라 안에 유지해야 할 때 Artisan으로 전환하세요. Chrome 프로세스를 시작하므로 해당 수명 주기를 고려해 계획하세요.
• 동일한 브라우저 충실도를 원하지만 브라우저를 로컬에서 실행하지 않고 엣지에서 렌더링하려면 Cloudflare로 전환하세요.
• 오피스 문서 변환이 필요하거나, 이미 Gotenberg를 운영 중이고 NextPDF로 이를 구동하려는 경우 Gotenberg로 전환하세요.

렌더러는 위협 표면을 넓힙니다

기본적으로 내장 파이프라인은 어떤 스크립트도 실행하지 않고 원격 리소스를 가져오지 않습니다. Artisan, Cloudflare, Gotenberg는 각각 브라우저 또는 네트워크 서비스를 통해 렌더링합니다. HTML을 신뢰할 수 없는 입력으로 간주하고, 사용자가 영향을 줄 수 있는 입력을 전달하기 전에 각 패키지의 보안 및 운영 페이지를 읽으세요.

Pro 또는 Enterprise 가 필요한 경우

코어 엔진은 비용이나 라이선스 없이 PDF를 생성, 렌더링, 검사합니다. NextPDF Pro와 NextPDF Enterprise는 nextpdf/premium 패키지의 두 가지 라이선스 티어입니다. 설치하면 기능이 추가되며, 코어 API는 변경되지 않습니다.

필요한 작업	티어	기능
PDF에 디지털 서명 (PAdES baseline)	Pro 티어	소프트웨어 키 서명 구현체.
아카이브용 PDF/A 출력 생성	Pro 티어	PDF/A 준수 및 아카이브 프로필.
전자 송장 임베드 (Factur-X / ZUGFeRD)	Pro 티어	전자 송장 계약 구현체.
하드웨어 보안 모듈(HSM)로 서명	Enterprise 티어	하드웨어 기반 키 작업.
적격 전자 서명 발급	Enterprise 티어	적격 서명 워크플로와 전체 규정 준수 범위.

다음 두 가지 규칙을 기준으로 삼으면 결정이 명확해집니다:

• 출력이 서명되지 않은 비아카이브 PDF라면 코어만으로 충분합니다. 라이선스가 필요하지 않습니다.
• 사용자가 nextpdf/premium을 설치하면 프레임워크 통합과 서버가 이를 자동으로 감지합니다. 동일한 컨테이너 키와 도구 카탈로그를 통해 추가 기능을 노출합니다. 이를 도입하기 위해 애플리케이션 코드를 변경할 필요는 없습니다.

의사 결정 요약

배포판

일반 PHP → 코어. 프레임워크 앱 → 해당 통합. 네트워크 경계 → 서버. Python 클라이언트 → Python SDK.

HTML 렌더러

지원되는 하위 집합, 의존성 없음 → writeHtml(). 자체 호스트의 브라우저 충실도 → Artisan. 엣지에서 → Cloudflare. 오피스 변환 → Gotenberg.

라이선스 티어

서명되지 않은 PDF → 코어. 서명, PDF/A, 전자 송장 → Pro. HSM 또는 적격 서명 → Enterprise.

아직 확신이 서지 않나요?

우선 코어를 설치하고 첫 PDF 만들기를 실행한 다음, 필요가 구체화될 때만 패키지를 추가하세요. 이 중 무엇이든 나중에 변경할 수 있습니다.

함께 보기

NextPDF 설치하기 모든 배포판과 렌더러에 대한 정확한 명령입니다.

첫 PDF 만들기 PHP 에서 PDF 를 생성하고 HTML 을 PDF 로 렌더링합니다.

통합 전체 확장 맵, 선택 가이드, 패키지별 매뉴얼입니다.

연결 (서버) MCP, REST, gRPC 를 통해 엔진을 네트워크 서비스로 실행합니다.