콘텐츠로 이동
NextPDF

통합 쿡북

통합 쿡북

섹션 제목: “통합 쿡북”

NextPDF core는 PHP에서 PDF 2.0을 렌더링합니다. 이 생태계의 9개 통합 패키지는 그 엔진을 프레임워크, 렌더링 백엔드, 레거시 코드베이스, 빌드 파이프라인 또는 네트워크 서비스에 연결합니다. 이 페이지는 각 통합이 어떤 용도로 쓰이는지 설명하고, 각 통합의 패키지 이름과 core 버전 제약을 기록하며(각 패키지의 composer.json에서 직접 읽음), 소스 저장소가 자체 docs/public/ 트리를 출시함에 따라 이곳에 편입되는 통합별 레시피로 연결합니다.

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

다섯 가지 통합 형태

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

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 빠른 시작 [[/integrations/laravel/quickstart/]]
Symfonynextpdf/symfony프레임워크^3.0 || ^5.2Symfony 빠른 시작 [[/integrations/symfony/quickstart/]]
CodeIgniter 4nextpdf/codeigniter프레임워크^3.0 || ^5.2CodeIgniter 빠른 시작 [[/integrations/codeigniter/quickstart/]]
Artisan (Chrome) 통합nextpdf/artisan렌더러 브리지^3.0 || ^5.2Artisan 빠른 시작 [[/integrations/artisan/quickstart/]]
Gotenbergnextpdf/gotenberg렌더러 브리지^3.0Gotenberg 빠른 시작 [[/integrations/gotenberg/quickstart/]]
Cloudflarenextpdf/cloudflare렌더러 브리지^3.0Cloudflare 빠른 시작 [[/integrations/cloudflare/quickstart/]]
Compat (legacy) 통합nextpdf/compat-legacy호환성 심^3.0Compat-legacy 빠른 시작 [[/integrations/compat-legacy/quickstart/]]
Backport builder 통합nextpdf/backport-builder빌드 도구해당 없음Backport 빠른 시작 [[/integrations/backport/quickstart/]]
Connect (server) 통합nextpdf/server네트워크 서비스^3.0Connect 빠른 시작 [[/integrations/connect/quickstart/]]

NextPDF는 nextpdf/server를 제품명 NextPDF Connect로 배포합니다. 해당 레시피는 connect slug 아래에 있습니다. nextpdf/compat-legacy는 compat 패밀리에서 출시되며, 해당 레시피는 compat-legacy slug 아래에 있습니다.

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

각 통합의 용도

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

프레임워크 통합

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

렌더러 브리지

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

호환성 심

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

빌드 도구

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

네트워크 서비스

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

레시피 링크가 해석되는 방식

섹션 제목: “레시피 링크가 해석되는 방식”

위의 각 [[…]] 플레이스홀더는 해당 통합 자체 저장소의 docs/public/ 아래에 작성되어 애그리게이터가 이 사이트로 가져오는 페이지를 미리 가리키는 참조입니다. 대상 slug는 하나의 규칙을 따릅니다:

/integrations/<integration>/<recipe>/

여기서 <integration> 토큰은 위의 패키지 및 core 제약 참조 표에서 직접 가져온 짧은 이름이며, 그 표의 각 행이 그러한 짧은 이름을 하나씩 제공합니다. 모든 통합이 출시하는 첫 레시피의 이름은 quickstart입니다. 그 이후의 레시피는 동일한 <integration> 루트 아래에서 추가 <recipe> 세그먼트를 사용합니다. 대상 페이지가 애그리게이트되기 전까지 해당 링크는 플레이스홀더이며 해석되지 않습니다. 이 색인은 어떤 대상 페이지에 대해서도 동작을 주장하지 않습니다. composer.json에서 검증된 패키지 사실과 각 저장소의 레시피가 차지할 slug만 기록합니다.

참고

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