가이드

한눈에 보기

가이드에서는 코드가 실행되는 환경에 NextPDF를 연결하는 방법을 설명합니다. 이 탭은 프로덕션 운영 점검 목록으로 시작한 다음, 도입 흐름에 따라 프레임워크 및 렌더러 통합, NextPDF Connect 서버, Python SDK, 엔진 확장 작성, 문제 해결이라는 다섯 가지 영역을 다룹니다. 아래의 각 섹션은 허브 페이지로 시작하고, 이어서 가장 자주 사용할 페이지를 나열합니다.

복사해 사용할 수 있는 작업 중심 레시피가 필요하다면 쿡북을 사용하십시오. 검증된 API 표면과 지원 매트릭스가 필요하다면 참조를 사용하십시오.

통합

여덟 개의 패키지는 코어 엔진을 프레임워크, 브라우저 렌더러, 엣지 서비스, 빌드 도구, 레거시 마이그레이션 경로에 연결합니다. 모든 패키지 섹션은 동일한 매뉴얼 구조 — 개요, 설치, 빠른 시작, 구성, API, 개발자 가이드, 프로덕션 사용, 보안, 문제 해결 — 를 따르므로 하나를 익히면 나머지에도 그대로 적용할 수 있습니다.

페이지	용도
통합	확장 맵과 선택 가이드입니다. 패키지를 고를 때 먼저 읽으십시오.
통합 API 색인	프레임워크, 렌더러, 전송, 빌드 도구별 API 표면을 다루는 확장 API 페이지로 안내합니다.
Laravel용 NextPDF	Laravel 프레임워크 어댑터입니다.
Symfony용 NextPDF	Symfony 프레임워크 어댑터입니다.
CodeIgniter용 NextPDF	CodeIgniter 프레임워크 어댑터입니다.
NextPDF Artisan	브라우저 수준 HTML 렌더링을 위한 Chrome 렌더러 브리지입니다.
NextPDF Cloudflare	Cloudflare용 엣지 배포 경로입니다.
NextPDF Gotenberg	Gotenberg 렌더러 브리지입니다.
TCPDF 호환성	TCPDF에서 이전하는 코드베이스를 위한 호환성 심입니다.
NextPDF Backport Builder	이전 PHP 런타임을 대상으로 하는 빌드 도구입니다.

NextPDF Connect

nextpdf/server 패키지는 엔진을 장기 실행 서비스로 구동합니다. 이 서비스는 고위험 도구를 휴먼 인 더 루프 확인 게이트 뒤에 배치하고, Model Context Protocol(MCP), Representational State Transfer(REST), gRPC를 통해 하나의 결정론적 도구 레지스트리를 제공합니다.

페이지	용도
NextPDF Connect	섹션 허브입니다. 서버의 개념, 구성, 운영을 다룹니다.
Connect 개요	패키지 경계와 세 가지 전송 방식을 설명합니다.
Connect 빠른 시작	첫 실행에 필요한 MCP 핸드셰이크와 그에 대응하는 REST 렌더링 요청을 다룹니다.
NextPDF Connect 구성	MCP YAML 파일과 `NEXTPDF_*` 환경 변수를 다룹니다.
NextPDF Connect API 레퍼런스	등록된 모든 도구, gRPC 심볼, 오류 모델 항목, 속도 제한을 설명합니다.
NextPDF Connect 배포	RoadRunner 워커 프로필, Docker, Redis 기반 저장소를 다룹니다.
Connect 보안 및 운영	인증, 전송 보안, 위협 모델을 다룹니다.

각 전송 방식에는 별도의 레퍼런스 페이지가 있습니다.

페이지	용도
MCP 전송	표준 입력과 출력을 통한 JSON-RPC 2.0 프레이밍을 다룹니다.
REST 전송	OpenAPI 3.1 계약, 베어러 인증, 등급별 게이트 라우트를 다룹니다.
gRPC 전송	`nextpdf.connect.v1` 서비스, 서버 스트리밍, 메타데이터 인증을 다룹니다.

Python SDK

NextPDF Connect 엔드포인트를 기반으로 Python 애플리케이션, 에이전트, 명령줄 환경에 인용 가능한 PDF 추출 기능을 제공합니다.

페이지	용도
Python SDK 가이드	`nextpdf` Python 패키지의 섹션 허브입니다.
Python SDK 개요	SDK의 역할과 Connect와의 관계를 설명합니다.
Python SDK 빠른 시작	`pip install nextpdf`로 설치하고 클라이언트가 서버를 가리키도록 설정합니다.
Python SDK API 레퍼런스	클라이언트 클래스, 메서드, 타입 지정 결과를 다룹니다.
Python CLI 도구	추출 워크플로를 위한 명령줄 인터페이스입니다.
Python MCP 서버	MCP를 사용하는 에이전트에 SDK를 노출합니다.

엔진 확장하기

공개 Service Provider Interface(SPI)를 사용하면 포크 없이 기능을 추가할 수 있습니다. 글꼴, 레이아웃 엔진, 이벤트 리스너, 서명 백엔드에 대한 계약을 제공하며, 각 계약에는 명시적인 안정성 약속이 함께 제공됩니다.

페이지	용도
확장 개발	확장 가능한 대상과 그 기반이 되는 안정성 약속을 설명합니다.
SPI 안정성 규칙	확장이 의존할 수 있는 하위 호환성 계약을 설명합니다.
사용자 지정 글꼴: FontRegistry 계약	자체 글꼴을 등록하고 배포합니다.
사용자 지정 레이아웃 엔진과 텍스트 가로채기	레이아웃 동작을 교체하거나 가로챕니다.
액션 트리거와 이벤트 리스너	문서 수명 주기를 관찰하고 반응합니다.
KMS 공급자 계약	자체 Key Management Service(KMS)에서 키를 공급합니다.

문제 해결

엔진 자체의 예외 분류 체계를 기반으로 증상과 해결 방법을 정리합니다. 클래스 이름이 아니라 관찰한 증상에서 시작하십시오.

페이지	용도
문제 해결	기술 자료의 허브입니다. 항목 구성 방식과 시작 지점을 다룹니다.
문제 해결: 글꼴 및 태깅	글꼴 임베딩 및 구조 태깅 실패를 다룹니다.
암호화 및 권한 문제 해결	암호화, 비밀번호, 권한 실패를 다룹니다.
문제 해결: 메모리 및 성능	메모리 한계와 처리량 문제를 다룹니다.
문제 해결: PDF/A 및 PDF/UA 검증	아카이브 및 접근성 검증 실패를 다룹니다.
문제 해결: 서명 및 타임스탬프	서명 및 타임스탬프 검증 실패를 다룹니다.

참고 항목

쿡북 — PHP, Connect, 통합을 위한 작업 중심 레시피입니다.
참조 — 검증된 API 표면, 지원 매트릭스, 오류 레퍼런스를 제공합니다.
NextPDF로 마이그레이션 — 시작하기 탭에서 다른 PDF 라이브러리로부터 이전하는 과정을 다룹니다.
NextPDF 둘러보기 — 엔진이 왜 현재 방식으로 동작하는지 설명하는 Insider_ 에세이입니다.