NextPDF Connect로 이미지 임베드하기

한눈에 보기

NextPDF Connect로 PDF에 이미지를 임베드합니다. 소스는 서버가 읽을 수 있는 파일 경로 또는 인라인 base64 데이터 URI입니다. 사용하는 도구는 create_pdf, add_image, output_pdf이며 — 모두 Core입니다. 이미지는 이미지 XObject로 그려지고, Do 연산자로 페인팅됩니다 (ISO 32000-2 §8.9).

설치

composer require nextpdf/server

전송 계층을 바인딩합니다. 지원되는 래스터 형식은 PNG, JPEG, GIF입니다.

개념 개요

add_image는 받은 source를 다음의 고정된 순서로 해석합니다:

데이터 URI — data:로 시작하는 문자열입니다. NextPDF는 MIME 타입과 base64 페이로드를 임시 파일로 디코딩해 임베드한 뒤, 임시 파일을 제거합니다.
원시 base64 — 긴 base64 문자열은 디코딩된 뒤 PNG로 처리됩니다.
파일 경로 — 그 밖의 모든 입력은 서버 프로세스가 읽을 수 있어야 하는 파일 시스템 경로로 처리됩니다.

이미지는 사용자 단위(기본값은 밀리미터)의 x/y 위치에 배치됩니다. width만 전달하면 가로세로 비율을 유지하도록 높이가 계산됩니다. width와 height를 모두 전달하면 이미지가 정확히 그 치수로 스케일링됩니다. 임베드된 객체는 페이지 콘텐츠에 페인팅되는 외부 객체입니다 (ISO 32000-2 §8.8).

API 표면

도구	역할	위험 등급
`create_pdf`	세션 열기	안전
`add_image`	경로 또는 데이터 URI에서 이미지 임베드	주의
`output_pdf`	PDF를 렌더링해 반환	승인 필요 / 검토 (base64)

도구 카탈로그가 공식 카탈로그입니다. 사용 가능한 도구는 설치된 등급에 따라 달라집니다.

코드 샘플 — 빠른 시작

create_pdf (A4 세로, 제목) → document_id.
source를 절대 경로로 설정하고 x, y, width를 지정한 add_image.
source를 data:image/png;base64,... URI로 설정하고 width와 height를 명시적으로 지정한 add_image.
output_pdf → base64.

코드 샘플 — 프로덕션

차트 렌더링이나 스크린샷처럼 호스트가 메모리에서 생성한 이미지에는 데이터 URI를 사용합니다. 이미 서버에 있는 에셋에는 파일 경로를 사용합니다. 항상 절대 경로를 사용합니다. 상대 경로는 서버의 작업 디렉터리를 기준으로 해석되며, 일반적으로 이는 호스트의 디렉터리가 아닙니다. 계속하기 전에 add_image 응답이 예상한 페이지에 이미지가 있음을 보고하는지 확인합니다.

엣지 케이스 및 주의 사항

경로를 찾을 수 없음. 존재하지 않는 파일 경로를 전달하면 이미지를 찾을 수 없음 오류가 반환됩니다.
지원되지 않는 형식. SVG, BMP, WebP는 거부됩니다. 먼저 이미지를 변환합니다.
잘못된 형식의 base64 / 데이터 URI. 잘못된 페이로드 또는 쉼표 구분자가 누락된 데이터 URI는 디코드 오류를 반환합니다.
크기가 너무 큰 이미지. 페이지보다 큰 이미지는 거부되지 않고 페이지 가장자리에서 잘립니다. 페이지에서 여백을 뺀 값을 기준으로 width/height를 계산합니다 (A4 세로는 210×297 mm).

성능

출력 크기는 이미지 콘텐츠에 비례해 증가합니다. 작은 이미지 두 개는 일반적으로 10–50 KB입니다. 이미지 임베드 예산은 텍스트 전용 예산보다 여유가 있습니다. 프로파일은 structural입니다.

보안 참고 사항

파일 경로 모드에서는 서버 프로세스의 권한으로 서버 파일 시스템을 읽습니다. 호스트가 전달할 수 있는 경로를 제한합니다. 신뢰할 수 없는 호출자가 source를 임의의 서버 파일로 지정하도록 허용해서는 안 됩니다. base64 모드는 바이트를 인라인으로 전달하므로 서버 경로 노출을 피합니다.

적합성

설명	사양	조항	reference_id
이미지는 `Do`로 페인팅되는 이미지 XObject입니다.	ISO 32000-2	§8.9
이미지는 페이지 콘텐츠에 페인팅되는 외부 객체입니다.	ISO 32000-2	§8.8

상업적 맥락

해당 없음 — 모든 도구가 Core입니다.

전송 계층 가용성

전송 계층	사용 가능	참고
MCP (stdio)	예	큰 base64 페이로드는 stdio 프레임 크기를 키웁니다.
REST	예	큰 에셋에는 멀티파트 또는 서버 경로를 우선 사용합니다.
gRPC	예	단항(unary); 메시지 크기 제한은 인라인 base64에 적용됩니다.

HITL 위험 등급

create_pdf는 안전, add_image는 주의, output_pdf는 승인 필요이며 — base64 모드에서는 검토 등급으로 낮아집니다. 경로 모드의 읽기는 서버 측에서 이루어지고 별도로 게이팅되지 않으므로, 정책 계층에서 이를 제한해야 합니다 (HITL 위험 등급).

확인 게이트 JSON 엔벌로프

base64 출력은 여기에 둡니다:

{ "allowed": true }