콘텐츠로 이동
NextPDF
getnextpdf.com

통합 쿡북

NextPDF core는 PHP에서 PDF 2.0을 렌더링합니다. 이 생태계의 9개 통합 패키지는 그 엔진을 프레임워크, 렌더링 백엔드, 레거시 코드베이스, 빌드 파이프라인 또는 네트워크 서비스에 연결합니다. 이 페이지는 각 통합이 어떤 용도로 쓰이는지 설명하고, 각 통합의 패키지 이름과 core 버전 제약을 기록하며(각 패키지의 composer.json에서 직접 읽음), 각 통합의 빠른 시작 레시피로 연결합니다.

이 페이지는 색인이므로 어떤 통합에 대해서도 동작을 주장하지 않습니다. 각 통합의 자체 저장소가 해당 레시피를 소유하며, 애그리게이터가 이를 이 사이트에 게시합니다. 사용 사례 기반 권장 사항은 통합 선택하기을 참조하세요. 실행 가능한 모든 레시피가 따르는 계약은 레시피 규약을 참조하세요.

다섯 가지 통합 형태

섹션 제목: “다섯 가지 통합 형태”

9개 패키지는 다섯 가지 형태로 나뉩니다. 각 형태는 해당 통합이 어떤 종류의 문제를 해결하는지 알려줍니다.

  • 프레임워크 통합은 NextPDF를 애플리케이션 프레임워크의 서비스 컨테이너와 요청 생명주기에 연결합니다: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. 하나를 설치하고, 서비스를 resolve한 다음, PDF 응답을 반환합니다.
  • 렌더러 브리지는 HTML-to-PDF 또는 Office-to-PDF 단계를 인-프로세스 파이프라인 대신 외부 렌더링 백엔드에 위임합니다: nextpdf/artisan (Chrome DevTools Protocol을 통한 헤드리스 Chrome), nextpdf/gotenberg (Gotenberg 마이크로서비스), nextpdf/cloudflare (엣지의 Cloudflare Browser Rendering).
  • **호환성 심(shim)**은 레거시 PDF 라이브러리를 대상으로 작성된 코드베이스가 재작성 없이 NextPDF를 호출할 수 있게 합니다: nextpdf/compat-legacy.
  • 빌드 도구는 8.4를 실행할 수 없는 런타임을 위해 NextPDF의 PHP 8.1 / 7.4 백포트를 생성합니다: nextpdf/backport-builder.
  • 네트워크 서비스는 AI 시스템과 원격 호출자를 위해 NextPDF를 REST, gRPC, Model Context Protocol로 노출합니다: nextpdf/server (NextPDF Connect로 배포).

HTTP를 사용하는 렌더러 브리지(nextpdf/gotenberg, nextpdf/cloudflare, 그리고 nextpdf/laravel의 HTTP 클라이언트 경로)는 호스트 애플리케이션이 제공하는 PSR-18 HTTP 클라이언트에 의존합니다. PSR-18 클라이언트는 인용된 PSR-18 §4 조항이 명시하듯이, 요청을 아예 보낼 수 없을 때에만 타입이 지정된 클라이언트 예외를 발생시킵니다. HTTP 4xx 또는 5xx 응답은 예외가 아니라 정상적인 반환값이며, 동일한 PSR-18 §4 조항도 이를 명시합니다. 원격 렌더러를 호출하는 레시피는 전송 오류와 비성공 상태를 두 가지 별개의 경우로 처리합니다.

패키지 및 core 제약 참조

섹션 제목: “패키지 및 core 제약 참조”

아래 모든 값은 명시된 패키지의 composer.json(권위 있는 출처)에서 읽었습니다. core 제약은 해당 패키지가 선언한 nextpdf/core 요구 사항입니다. nextpdf/backport-builder는 런타임에서 엔진에 의존하는 대신 엔진 소스를 변환하므로 nextpdf/core 요구 사항을 선언하지 않습니다.

통합패키지형태Core 제약레시피
Laravelnextpdf/laravel프레임워크^3.0 || ^5.2Laravel 빠른 시작
Symfonynextpdf/symfony프레임워크^3.0 || ^5.2Symfony 빠른 시작
CodeIgniter 4nextpdf/codeigniter프레임워크^3.0 || ^5.2CodeIgniter 빠른 시작
Artisan (Chrome) 통합nextpdf/artisan렌더러 브리지^3.0 || ^5.2Artisan 빠른 시작
Gotenbergnextpdf/gotenberg렌더러 브리지^3.0Gotenberg 빠른 시작
Cloudflarenextpdf/cloudflare렌더러 브리지^3.0Cloudflare 빠른 시작
Compat (legacy) 통합nextpdf/compat-legacy호환성 심^3.0TCPDF-compat 빠른 시작
Backport builder 통합nextpdf/backport-builder빌드 도구해당 없음Backport 빠른 시작
Connect (server) 통합nextpdf/server네트워크 서비스^3.0Connect 빠른 시작

NextPDF는 nextpdf/server를 제품명 NextPDF Connect로 배포합니다. 해당 레시피는 최상위 connect slug 아래에 있습니다. nextpdf/compat-legacy는 compat 패밀리에서 출시되며, 해당 레시피는 자신이 에뮬레이션하는 표면의 이름을 딴 tcpdf-compat slug 아래에 있습니다.

모든 패키지는 자체 런타임에서 PHP >=8.4 <9.0을 요구합니다. nextpdf/backport-builder는 PHP 8.1(및 7.4 타겟)에서 실행되는 아티팩트를 생성하기 위해 특별히 존재합니다. 이전 런타임에서 실행되는 것은 빌더가 아니라 결과물인 백포트된 엔진입니다.

각 통합의 용도

섹션 제목: “각 통합의 용도”

프레임워크 통합

섹션 제목: “프레임워크 통합”
  • nextpdf/laravel — Laravel 12 서비스 프로바이더, 퍼사드, PDF 응답 헬퍼입니다. 애플리케이션이 Laravel 앱이며 NextPDF를 컨테이너에서 resolve해 수작업 배선 없이 HTTP 응답으로 반환하려는 경우 사용하세요. 레시피: Laravel 빠른 시작.
  • nextpdf/symfony — 의존성 주입 서비스와 PDF 응답 헬퍼를 갖춘 Symfony 7 번들입니다. 애플리케이션이 Symfony 앱일 때 사용하세요. 번들은 엔진을 서비스로 등록하고 symfony/http-foundation 응답과 통합됩니다. 레시피: Symfony 빠른 시작.
  • nextpdf/codeigniter — CodeIgniter 4 서비스, 라이브러리 래퍼, PDF 응답 헬퍼입니다. 애플리케이션이 CodeIgniter 4 앱이며 프레임워크의 서비스 로케이터를 통해 NextPDF를 사용하려는 경우 사용하세요. 레시피: CodeIgniter 빠른 시작.

렌더러 브리지

섹션 제목: “렌더러 브리지”
  • nextpdf/artisan — Chrome DevTools Protocol을 통한 헤드리스 Chrome 렌더러입니다. 인-프로세스 HTML 파이프라인이 목표로 하지 않는 수준의 레이아웃 충실도를 위해 문서에 브라우저 CSS 엔진이 필요하고, 애플리케이션 근처에서 Chrome 프로세스를 실행할 수 있을 때 사용하세요. 레시피: Artisan 빠른 시작.
  • nextpdf/gotenberg — Gotenberg 마이크로서비스를 통한 Office-to-PDF 및 HTML-to-PDF 변환입니다. 입력이 Office 문서이거나 렌더링을 별도 서비스에서 아웃-오브-프로세스로 실행해야 할 때 사용하세요. 호스트가 제공하는 PSR-18 클라이언트를 통해 HTTP로 통신합니다. 레시피: Gotenberg 빠른 시작.
  • nextpdf/cloudflare — Cloudflare Browser Rendering API를 통한 서버리스 렌더링입니다. 운영해야 하는 장수명 브라우저 프로세스 없이 엣지에서 렌더링을 실행해야 할 때 사용하세요. 호스트가 제공하는 PSR-18 클라이언트를 통해 HTTP로 통신합니다. 레시피: Cloudflare 빠른 시작.

호환성 심

섹션 제목: “호환성 심”
  • nextpdf/compat-legacy — 레거시 PDF 라이브러리를 대상으로 작성된 코드베이스를 위한 호환성 계층입니다. 기존 코드에서 호출 지점을 먼저 재작성하지 않고 NextPDF를 호출해야 할 때 사용하세요. 이는 영구적인 의존성이 아니라 마이그레이션 보조 수단입니다. 레시피: TCPDF-compat 빠른 시작.

빌드 도구

섹션 제목: “빌드 도구”
  • nextpdf/backport-builder — NextPDF의 PHP 8.1(및 7.4 타겟) 빌드를 생성하는 Rector 기반 다운그레이드 파이프라인입니다. 런타임을 PHP 8.4로 옮길 수 없지만 그곳에 엔진이 필요한 경우에 사용하세요. 이것은 빌드 인프라입니다. 애플리케이션의 런타임 의존성에 추가되지 않습니다. 레시피: Backport 빠른 시작.

네트워크 서비스

섹션 제목: “네트워크 서비스”
  • nextpdf/server (NextPDF Connect) — NextPDF를 REST API, gRPC 서비스, Model Context Protocol로 노출합니다. 호출자가 원격이거나, 다른 언어로 작성되어 있거나, AI 시스템에 PHP 라이브러리가 아닌 도구 엔드포인트가 필요할 때 사용하세요. 레시피: Connect 빠른 시작.

레시피 slug 구성 방식

섹션 제목: “레시피 slug 구성 방식”

레시피는 /integrations/<integration>/<recipe>/ 아래에 위치하며, 여기서 <integration>은 위 참조 표의 짧은 이름입니다(단, Connect 레시피는 최상위 connect slug 아래에 있습니다). 모든 통합이 출시하는 첫 레시피의 이름은 quickstart입니다. 그 이후의 레시피는 동일한 루트 아래에서 추가 <recipe> 세그먼트를 사용합니다. 이 색인은 어떤 대상 페이지에 대해서도 동작을 주장하지 않습니다. composer.json에서 검증된 패키지 사실과 각 저장소의 레시피가 차지하는 slug만 기록합니다.

참고

섹션 제목: “참고”
  • 통합 선택하기 — 사용 사례를 통합에 매핑하는 의사결정 매트릭스입니다.
  • 레시피 규약 — 이 쿡북의 실행 가능한 모든 레시피가 따르는 계약입니다.