NextPDF FAQ

한눈에 보기

이 페이지는 NextPDF를 평가하거나 새 프로젝트를 시작할 때 가장 먼저 떠오르는 질문에 답합니다. 각 답변은 짧고, 그것을 자세히 다루는 페이지로 연결됩니다. NextPDF는 ISO 32000-2가 정의하는 파일 형식인 Portable Document Format (PDF) 2.0 문서를 생성하고 검사하는 PHP 8.4 엔진입니다.

완전히 처음이라면 먼저 시작하기를 읽은 뒤, 구체적인 내용은 여기로 돌아와서 확인하십시오.

시작하기

Core, Pro, Enterprise 중 어느 에디션이 필요한가요?

Core로 시작하십시오. 오픈 소스 코어(nextpdf/core)는 PDF 출력을 생성하고, 지원되는 HTML을 PDF로 렌더링하며, Apache-2.0 라이선스 아래 무료로 PDF를 검사합니다. Core는 이미 PDF Advanced Electronic Signatures (PAdES) B-B 및 B-T 기준선 레벨에 대한 CMS SignedData 서명을 생성합니다. 고급 생성 및 문서 작업, 전자 인보이스 출력(Factur-X / ZUGFeRD), 또는 원격, 클라우드-KMS, 순차 서명과 같은 고급 서명 워크플로가 필요할 때 Pro를 선택하십시오. PDF/A 보관 작성 워크플로, Document Security Store 및 문서 타임스탬프를 갖춘 PAdES 장기 레벨(B-LT / B-LTA), 하드웨어 보안 모듈(HSM)을 통한 하드웨어 기반 서명, 또는 적격 전자 서명이 필요할 때 Enterprise를 선택하십시오. Pro와 Enterprise는 유료 제품 라인인 NextPDF Premium의 두 가지 라이선스 에디션입니다. 경로 선택하기를 참고하십시오.

정말로 Apache-2.0인가요?

코어에 대해서는 예입니다. nextpdf/core는 "license": "Apache-2.0"을 선언하고 그 LICENSE 파일에 Apache License 2.0 전문을 포함합니다. 귀속 및 NOTICE 요구 사항(Apache-2.0 §4)을 준수하는 한, 코어를 사용, 수정, 재배포, 상업화할 수 있습니다. NextPDF Pro와 NextPDF Enterprise는 독점 상용 에디션이며 그 라이선스에 포함되지 않습니다. NextPDF 이름과 로고는 코드 라이선스와 별개인 상표입니다. 라이선스를 참고하십시오.

최소 PHP 버전은 무엇인가요?

PHP 8.4입니다. 패키지 제약은 >=8.4 <9.0이므로 Composer는 PHP 8.3 이하나 PHP 9에는 설치를 거부합니다. NextPDF는 하나의 현대적 런타임을 대상으로 하며 그 언어 기능을 직접 사용합니다. NextPDF 설치를 참고하십시오.

외부 바이너리나 헤드리스 브라우저가 필요한가요?

아니요, 코어 엔진에는 필요하지 않습니다. 네이티브 엔진은 PHP와 표준 PHP 확장으로 구현되며, 외부 PDF 바이너리도 필수 헤드리스 브라우저도 없습니다. 플루언트 API와 내장 writeHtml() HTML 파이프라인은 브라우저 없이, 네트워크 호출 없이 인프로세스로 실행됩니다. Chrome이나 Chromium 바이너리는 선택 사항이며, nextpdf/artisan으로 별도 설치하는 Artisan 렌더러(writeHtmlChrome())에만 필요합니다. Cloudflare 및 Gotenberg 브리지도 선택 사항이며 서비스로 호출합니다. 경로 선택하기를 참고하십시오.

어떤 PHP 확장이 필요한가요?

코어의 composer.json은 표준 확장 ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl, ext-openssl을 요구하며, 이들은 흔히 사용 가능한 PHP 확장입니다. 런타임에 설치되고 활성화되어 있는지 확인하십시오. ext-curl은 선택적 네트워크 왕복 — RFC 3161 타임스탬프와 원격 자산 가져오기 — 을 뒷받침하므로 오프라인 네이티브 생성은 이를 사용하지 않지만, Composer는 여전히 이를 하드 요구 사항으로 나열합니다. 통합은 부팅 중에 필요한 확장을 확인하고, 누락된 것이 있으면 명확한 메시지와 함께 중단됩니다. 전체 목록은 패키지 composer.json에 있습니다. NextPDF 설치를 참고하십시오.

첫 PDF를 어떻게 생성하나요?

코어를 설치한 뒤 플루언트 API로 문서를 구축하십시오.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

첫 PDF에서 단계별로 살펴보십시오.

에디션 및 라이선스

Core에 기능 제한이나 워터마크가 있나요?

없습니다. Core는 Core 기능 세트를 위한 오픈 소스 엔진으로, 워터마크도 나그 화면도 없습니다. Core 기능 세트 — 생성, 검사, 암호화, PDF/A 및 PDF/UA 출력 기본 요소, 그리고 소프트웨어 키 B-B/B-T 서명(프리미엄의 장기 검증 및 키 보관 워크플로 제외) — 에 대해 Core는 완전합니다. 평가 워터마크는 프리미엄 평가 부여에만 적용되며, 그 경우 제거 가능한 표시 뒤에서 전체 Pro 및 Enterprise 기능 세트를 테스트할 수 있습니다. 유료 라이선스는 애플리케이션 코드 변경 없이 이를 제거합니다. 라이선스 및 활성화를 참고하십시오.

Pro나 Enterprise로 업그레이드하려면 코드 변경이 필요한가요?

대체로 필요하지 않습니다. nextpdf/premium을 설치하면 프레임워크 통합과 서버가 자동으로 그것을 감지하고 추가 기능을 노출합니다. 대부분의 애플리케이션은 동일한 상위 수준 통합 지점을 유지하지만, 일부 프리미엄 워크플로는 구성이나 기능별 호출을 요구할 수 있습니다. 배포당 한 번 서명된 라이선스 봉투를 활성화합니다. 라이선스 및 활성화를 참고하십시오.

코어를 비공개 소스 상용 제품에 사용할 수 있나요?

예. Apache License 2.0에는 비상업적 제한이 없습니다. 귀속 및 NOTICE 의무를 준수하고 코드 라이선스를 NextPDF 브랜드 사용 허가로 취급하지 않는 한, 코어를 비공개 소스, 유료, 또는 내부 상용 제품에 사용할 수 있습니다. 라이선스와 상표 및 브랜드 사용을 참고하십시오.

기능

PDF를 읽고 파싱할 수 있나요, 아니면 쓰기만 가능한가요?

둘 다 가능하지만 한 가지 단서가 있습니다. NextPDF는 PDF를 쓰는 동시에 읽습니다. Inspect 모듈은 기존 파일을 복잡도, 글꼴, 이미지, 위험 데이터를 담은 구조화된 InspectResult로 읽어 들이며, 기존 문서를 병합하고 분할할 수 있습니다. Inspect는 experimental로 표시되어 있으므로 그 결과 형태가 minor 버전 사이에 바뀔 수 있습니다 — 장기적인 계약이 아니라 진단과 게이팅에 사용하십시오. Inspect 모듈을 참고하십시오.

선택 가능하고 검색 가능한 텍스트를 생성하나요?

예. 플루언트 API와 내장 writeHtml() 파이프라인 모두 래스터화된 이미지가 아니라 실제 텍스트 콘텐츠를 내보내므로, 출력은 선택 가능하고 검색 가능합니다. Artisan 렌더러의 writeHtmlChrome()도 텍스트를 선택 가능한 상태로 유지합니다. 첫 PDF를 참고하십시오.

HTML 및 CSS 렌더링은 어떻게 작동하나요?

코어 엔진은 순수 PHP HTML 파이프라인을 포함합니다. writeHtml()은 지원되는 CSS 하위 집합으로 HTML 조각을 브라우저 없이, 네트워크 호출 없이 페이지에 직접 렌더링합니다. 레이아웃에 전체 브라우저 충실도가 필요할 때 — 예를 들어 flexbox, grid, 또는 웹 글꼴 — Artisan 렌더러를 설치하고 writeHtmlChrome()을 호출하십시오. 속성에 의존하기 전에 CSS 지원 매트릭스를 확인하십시오.

글꼴은 어떻게 작동하나요?

Helvetica 같은 내장 표준 글꼴 별칭은 단순한 WinAnsi 텍스트에 대해 설정 없이 작동하므로, 첫 문서에는 글꼴 파일이 필요하지 않습니다. 내장 라틴 표준 글꼴은 기본 WinAnsi 텍스트에 적합하며, Symbol과 ZapfDingbats는 자체 인코딩을 사용합니다. 다른 스크립트를 렌더링하려면 해당 스크립트의 문자 맵과 셰이핑 경로를 지원하는 글꼴을 등록하고 임베드하십시오. 글꼴 지원 매트릭스와 Font 모듈을 참고하십시오.

PDF/A 및 접근성(PDF/UA)을 지원하나요?

예, 단 명확한 경계와 함께입니다. 프로필 지원은 적합성이 아닙니다. 코어는 적합성 판별기와 태깅 기본 요소를 제공합니다 — enableTaggedPdf()는 PDF/UA 워크플로에 사용되는 태그된 PDF 구조 출력을 활성화하고, enablePdfA()는 Core에서 PDF/A 출력 프로필을 선택합니다. 프리미엄 에디션은 그 위에 상위 수준의 보관 작성 워크플로와 도구(검증, 정책, 프로덕션 운영)를 더합니다. NextPDF는 프로필이 요구하는 구조적 아티팩트를 내보내며, 특정 파일이 실제로 적합한지는 veraPDF 같은 독립적인 검증기가 결정합니다. 적합성과 Accessibility 모듈을 참고하십시오.

PDF에 어떻게 서명하나요?

코어는 Cryptographic Message Syntax (CMS) SignedData 서명을 생성할 수 있고, 구성된 서명 공급자를 통해 지원되는 소프트웨어 키 알고리즘을 사용하여 RFC 3161 타임스탬프(B-T 레벨)를 적용할 수 있습니다. 코드는 SignerInterface 계약에 의존하므로 동일한 호출이 모든 에디션에서 작동합니다. PAdES B-LT 및 B-LTA 장기 레벨, HSM 및 PKCS#11 키 보관, 그리고 적격 서명은 Enterprise 기능입니다. 클라우드 및 KMS 기반 서명 워크플로는 Pro에서 제공됩니다. Core는 B-B 및 B-T 기준선 구조를 생성합니다. Signing 모듈을 참고하십시오.

프로덕션

워커 안전하고 스레드 안전한가요?

Document는 일회용입니다. 하나를 작성한 뒤에는 그것을 재사용하는 대신 다음 문서를 위한 새 인스턴스를 만드십시오. 이는 PHP-FPM, 큐 워커, 프레임워크가 사용하는 요청별·작업별 모델에 자연스럽게 들어맞습니다 — 각 작업 단위가 자체 문서를 구축합니다. 신뢰할 수 없는 입력을 파싱하거나 구성할 때는 그 작업을 제약된 워커에서 실행하고 리소스 가드(maxFiles, maxTotalBytes, maxBytes)를 타이트하게 유지하십시오. Document 모듈과 엔진 위협 모델을 참고하십시오.

출력이 결정적인가요?

구조적으로는 결정적이지만 기본적으로 바이트 단위로 동일하지는 않습니다. 동일한 입력을 두 번 실행하면 구조적으로 동등한 PDF가 생성되지만, 각각 새로운 트레일러와 문서 /ID를 담으므로 바이트가 다릅니다. 서명과 타임스탬프는 설계상 실행마다 추가적인 변이를 더합니다. 동일한 바이트를 기대하기보다는 구조적 동등성을 중심으로 비교를 계획하거나, 변동하는 필드를 정규화하십시오.

어떻게 배포하나요?

composer.lock을 커밋하여 배포된 모든 워커가 동일한 엔진 버전을 해석하도록 한 뒤, 다른 PHP 라이브러리와 마찬가지로 배포하십시오 — 네이티브 생성에는 데몬, 브라우저, 네트워크가 필요하지 않습니다. 타임스탬프(B-T), 원격 자산, 또는 선택적 브라우저 브리지는 구성된 네트워크 접근을 요구합니다. PHP가 아닌 서비스가 엔진을 필요로 한다면, Model Context Protocol (MCP), REST, gRPC를 통해 엔진을 노출하는 NextPDF Server를 실행하십시오. 프리미엄의 경우 서명된 라이선스 봉투를 배포가 로드하는 위치에 두고 일회성 활성화 단계를 실행하십시오. 캐시된 라이선스 상태 덕분에 정상적인 처리에는 라이선스 서비스가 필요하지 않으므로, 에어갭 배포가 지원됩니다. NextPDF 설치와 라이선스 및 활성화를 참고하십시오.

문제가 생겼을 때 실패를 어디로 가져가나요?

NextPDF는 문자열 오류 코드가 아니라 PHP 예외 클래스로 오류를 보고하며, 컨텍스트 인식 예외는 구조화된 진단 필드를 담습니다. 문제 해결는 일반적인 서명, PDF/A, PDF/UA, 글꼴, 태깅, 암호화 실패를 그 원인과 해결로 매핑합니다.