통합 선택하기
통합 선택하기
섹션 제목: “통합 선택하기”이 페이지는 사용 사례별로 어떤 통합이 이를 처리하는지 매핑합니다. 모든 권장 사항은 소스 저장소에서 직접 확인한 패키지의 composer.json 설명과 명시된 목적만을 근거로 합니다. 두 통합이 겹칠 때는 이 페이지에서 둘을 구분하는 요소를 짚고, 최종 결정은 사용자에게 맡깁니다.
자신의 상황에 맞는 행에서 시작하면 됩니다.
여기서 시작: 현재 무엇을 사용하고 있습니까?
섹션 제목: “여기서 시작: 현재 무엇을 사용하고 있습니까?”| 현재 상황 … | 사용할 통합 | 이유 (검증된 목적) |
|---|---|---|
| Laravel 12 애플리케이션 | nextpdf/laravel | Laravel 프레임워크 통합: 서비스 프로바이더, 파사드, PDF 응답 헬퍼. |
| Symfony 7 애플리케이션 | nextpdf/symfony | Symfony 번들: DI 서비스 및 PDF 응답 헬퍼. |
| CodeIgniter 4 애플리케이션 | nextpdf/codeigniter | CodeIgniter 4 서비스, 라이브러리 래퍼 및 PDF 응답 헬퍼. |
| 프레임워크 없는 PHP 앱 | nextpdf/core 직접 사용 | 프레임워크 통합이 필요 없습니다. 엔진은 일반 라이브러리입니다. |
| 브라우저 CSS 엔진이 필요한 HTML이고, Chrome을 실행할 수 있는 경우 | nextpdf/artisan | 브라우저 수준의 CSS 레이아웃이 필요한 HTML용 Chrome CDP 렌더러. |
| DOCX, XLSX 또는 ODT와 같은 변환 대상 Office 문서 | nextpdf/gotenberg | Gotenberg 마이크로서비스를 통한 Office-PDF 변환. |
| 운영할 브라우저 프로세스 없이 렌더링해야 하는 경우 | nextpdf/cloudflare | 에지에서 Cloudflare Browser Rendering API를 통한 서버리스 렌더링. |
| 레거시 PDF 라이브러리를 대상으로 작성된 코드 | nextpdf/compat-legacy | 레거시 PDF 라이브러리 호환성 계층. 호출 지점을 다시 작성하지 않고 NextPDF를 호출합니다. |
| PHP 8.1 / 7.4에 묶여 있는 런타임 | nextpdf/backport-builder | 엔진의 8.1 / 7.4 대상을 빌드하는 Rector 다운그레이드 파이프라인. |
| 원격 호출자, 다른 언어 또는 AI 시스템 | nextpdf/server | NextPDF Connect: 원격 실행을 위한 REST, gRPC 및 Model Context Protocol 인터페이스. |
두 통합이 모두 적합할 수 있을 때
섹션 제목: “두 통합이 모두 적합할 수 있을 때”HTML을 PDF로 렌더링: Artisan vs Gotenberg vs Cloudflare vs core
섹션 제목: “HTML을 PDF로 렌더링: Artisan vs Gotenberg vs Cloudflare vs core”세 렌더러 브리지는 모두 마크업을 PDF로 변환합니다. 품질이 아니라 작동 방식이 다르므로, 운영상의 차이가 결정 요소가 됩니다.
- **
nextpdf/artisan**은 Chrome DevTools Protocol을 통해 헤드리스 Chrome을 구동합니다. 애플리케이션에서 접근 가능한 Chrome 프로세스가 필요합니다. 해당 프로세스를 운영할 수 있고 문서에 브라우저 CSS 엔진이 필요할 때 선택합니다. - **
nextpdf/gotenberg**은 HTTP를 통해 프로세스 외부의 Gotenberg 마이크로서비스를 호출합니다. 렌더링을 자체 서비스로 격리해야 하거나 입력이 Office 문서일 때 선택합니다. Gotenberg는 셋 중 명시된 목적에 Office-PDF 변환이 포함된 유일한 통합입니다. - **
nextpdf/cloudflare**은 Cloudflare Browser Rendering API를 호출합니다. 실행하거나 패치할 브라우저 프로세스 없이 edge/serverless 렌더링을 원할 때 선택합니다. - 프로세스 내 NextPDF 코어 HTML 파이프라인은 위 항목 중 어느 것도 필요하지 않습니다. 렌더러 브리지는 프로세스 내 파이프라인으로 문서에 필요한 레이아웃 충실도나 프로세스 격리를 충족할 수 없을 때만 사용합니다. 브리지는 기본 경로가 아니라 해당 요구 수준을 충족하기 위한 의도적인 선택입니다.
두 HTTP 브리지(nextpdf/gotenberg, nextpdf/cloudflare)에는 호스트가 제공하는 PSR-18 HTTP 클라이언트가 필요합니다. 각 레시피는 전송 실패와 성공이 아닌 HTTP 상태를 별개의 두 결과로 취급합니다.
Office 문서 변환
섹션 제목: “Office 문서 변환”nextpdf/gotenberg는 검증된 composer.json 설명에서 Office-PDF 변환을 명시하는 통합입니다. 다른 렌더러 브리지는 Office 입력이 아닌 HTML 렌더링을 설명합니다. 소스가 DOCX/XLSX/ODT라면 이것이 적합한 선택입니다.
레거시 PDF 라이브러리에서 마이그레이션
섹션 제목: “레거시 PDF 라이브러리에서 마이그레이션”명시된 목적상 nextpdf/compat-legacy는 레거시 PDF 라이브러리를 대상으로 작성된 코드베이스를 위한 호환성 계층입니다. 이를 통해 기존 호출 지점을 다시 작성하기 전에 NextPDF에 접근할 수 있습니다. 영구적인 런타임 종속성이 아니라 나중에 제거할 마이그레이션 보조 도구로 취급합니다. 새 코드는 nextpdf/core(또는 해당 프레임워크 통합)를 직접 호출합니다.
PHP 8.1 또는 7.4에서 실행
섹션 제목: “PHP 8.1 또는 7.4에서 실행”모든 에코시스템 패키지는 PHP >=8.4 <9.0을 선언합니다. nextpdf/backport-builder는 이 제약을 해결하기 위해 존재합니다. 명시된 목적은 PHP 8.1+(및 7.4 대상) 아티팩트를 빌드하기 위한 Rector 다운그레이드 파이프라인입니다. 이것은 애플리케이션의 런타임 종속성이 아니라 빌드 도구입니다. 빌더를 실행해 백포트된 엔진을 생성한 다음, 그 엔진을 배포합니다.
PHP가 아닌 호출자 또는 AI 에이전트
섹션 제목: “PHP가 아닌 호출자 또는 AI 에이전트”nextpdf/server(NextPDF Connect)는 REST API, gRPC 서비스 및 Model Context Protocol을 통해 엔진을 노출합니다. 호출자가 원격에 있거나, 다른 언어를 사용하거나, PHP 라이브러리가 아닌 도구 엔드포인트를 사용하는 AI 시스템일 때 선택합니다. 동일한 프로세스 내의 PHP 애플리케이션은 네트워크 홉 비용을 치르는 대신 nextpdf/core 또는 프레임워크 통합을 사용해야 합니다.
둘 이상의 통합을 함께 사용하기
섹션 제목: “둘 이상의 통합을 함께 사용하기”프레임워크 통합과 렌더러 브리지는 서로 다른 계층에서 작동하므로 둘 다 설치할 수 있습니다. 프레임워크 통합은 컨테이너 연결과 HTTP 응답을 처리하고, 렌더러 브리지는 렌더링 백엔드를 처리합니다. 결합된 종속성 집합을 해결할 때는 각 패키지가 어떤 nextpdf/core 버전을 허용하는지 확인합니다. 이 정보는 통합 쿡북 인덱스의 코어 제약 참조가 신뢰할 수 있는 출처입니다. 조합별 레시피는 관련 저장소에 있으며 해당 인덱스에서 링크됩니다.