NextPDF Artisan 개요

한눈에 보기

NextPDF Artisan은 NextPDF용 Chrome 브리지입니다. Chrome DevTools Protocol을 통해 HTML 조각을 헤드리스 Chrome 프로세스로 전송하고, printToPDF 출력을 캡처한 다음 그 결과를 대상 문서에 Form XObject로 삽입합니다. 삽입된 텍스트는 계속 선택하고 검색할 수 있습니다.

개념 개요

Artisan 패키지(nextpdf/artisan)는 오픈 소스 NextPDF 엔진을 확장해 레이아웃을 Chrome에 위임하는 렌더러로 만듭니다. NextPDF의 기본 HTML 파이프라인은 이미 광범위한 CSS 하위 집합을 다룹니다. Artisan 브리지는 Chrome 수준의 레이아웃이 필요한 문서, 즉 CSS flexbox 및 grid, data URI에서 로드한 사용자 지정 웹 글꼴, 복잡한 선택자를 사용하면서도 래스터화된 스크린샷이 아니라 벡터 텍스트를 생성해야 하는 문서를 위해 존재합니다.

이 브리지는 작고 목적이 분명한 구성 요소로 이루어진 파이프라인입니다. ChromeHtmlRenderer는 렌더링을 조율합니다. ChromeSecurityPolicy는 입력을 검증하고 엄격하게 잠긴 HTML 문서로 감쌉니다. BrowserPool은 Chrome 프로세스 수명 주기를 관리합니다. ViewportCalculator는 PDF 포인트를 CSS 픽셀로 매핑합니다. NextPDF\Parser 리더가 Chrome 출력을 파싱하고, PageImporter가 이를 Form XObject로 변환합니다. 모든 구성 요소는 final이며, 생성자 주입 방식을 사용하고, PHPStan 레벨 10으로 타입이 지정되어 있습니다.

이 브리지는 외부 종속성에 의존합니다. chrome-php/chrome 라이브러리(^1.15)와 PHP 프로세스가 접근할 수 있는 Chrome 또는 Chromium 바이너리가 필요합니다. 둘 중 어느 것도 번들로 포함되지 않습니다. 라이브러리가 없으면 브리지는 조용히 성능을 낮추지 않고 ChromeNotAvailableException을 발생시킵니다. 실패 모드는 /integrations/artisan/failure-modes/ 및 /integrations/artisan/troubleshooting/ 페이지를 참조하세요.

입력은 ChromeSecurityPolicy::validate()를 통과하기 전에는 결코 Chrome에 도달하지 않으며, Chrome이 받는 문서는 항상 엄격한 Content-Security-Policy와 심층 방어 CDP 네트워크 차단으로 감싸집니다. 브리지는 신뢰할 수 없을 수 있는 HTML을 처리하므로, 전송 및 격리 방식은 여기서 요약하는 대신 /integrations/artisan/security-and-operations/ 페이지에 명시적으로 문서화되어 있습니다.

이는 출시된 패키지에서 관찰된 동작이며, src/Artisan/ 및 tests/Unit/Artisan/ 스위트에 대해 검증되었습니다. 대화형 Chrome 브라우저와 픽셀 단위로 동일하다는 주장은 아닙니다. 애니메이션은 마지막 프레임에서 캡처되고, 레이아웃은 JavaScript에 의존하지 않으며, 첫 번째 Chrome 페이지만 가져옵니다.

아키텍처

Diagram

구성 요소 책임

구성 요소	책임	소스
`ChromeHtmlRenderer`	단일 렌더링을 조율하고 `ChromeRenderResult`를 반환	`src/Artisan/ChromeHtmlRenderer.php`
`ChromeRendererConfig`	불변 구성 값 객체	`src/Artisan/ChromeRendererConfig.php`
`ChromeSecurityPolicy`	입력 검증 + 보안 HTML 봉투	`src/Artisan/ChromeSecurityPolicy.php`
`BrowserPool`	Chrome 프로세스 수명 주기 및 재시작 정책	`src/Artisan/BrowserPool.php`
`ViewportCalculator`	72 pt/inch ↔ 96 px/inch 변환	`src/Artisan/ViewportCalculator.php`
`ChromeRenderResult`	타입이 지정된 렌더링 출력(`ChromeRenderResultInterface`) 제공	`src/Artisan/ChromeRenderResult.php`
`PageImporter`	파싱된 Chrome 페이지 → `ImportedFormXObject`	`src/Artisan/PageImporter.php`
`EInvoiceServiceFactory`	Premium 전자 인보이스 계약을 위한 컨테이너 없는 팩토리	`src/Artisan/EInvoiceServiceFactory.php`

엣지 케이스 및 주의 사항

버전 계보. 게시된 Composer 아티팩트에는 v0.1.0 태그가 지정되어 있습니다. 소스 docblock에는 @since 1.7.0(Chrome 브리지)과 @since 1.1.0(전자 인보이스 팩토리)이 포함되어 있으며, 둘 다 이름이 변경되기 전 nextpdf/core 버전 라인에서 상속되었습니다. 이 패키지는 2.0.0 CHANGELOG 항목에서 nextpdf/artisan으로 이름이 변경되었습니다. Composer 태그를 기준 설치 버전으로 간주하고, @since 마커는 엔진 버전 출처로 취급하세요.
첫 번째 페이지만. PageImporter::import()는 기본적으로 페이지 인덱스 0을 사용합니다. 두 번째 Chrome 페이지로 넘치는 콘텐츠는 명시적인 높이를 지정하지 않는 한 잘립니다. /integrations/artisan/production-usage/ 페이지에서 다룹니다.
DI 컨테이너 없음. Artisan은 컨테이너를 사용하지 않습니다. EInvoiceServiceFactory는 서비스 컨테이너가 없는 환경에 일관된 인스턴스화 표면을 제공합니다. /integrations/artisan/boot-and-discovery/를 참조하세요.

성능

각 렌더링에는 호출당 한 번씩 Chrome 페이지 로드와 printToPDF 비용이 듭니다. BrowserPool은 렌더링 사이에 Chrome 프로세스를 계속 살려 두며, 메모리 증가를 제한하기 위해 100회 렌더링마다 프로세스를 재시작합니다. Big-O를 좌우하는 것은 브리지 자체가 아니라 입력에 대한 Chrome의 레이아웃입니다. 이 페이지의 참조 흐름에 대해 측정된 예산은 프런트매터의 performance_budget와 /integrations/artisan/production-usage/ 페이지를 참조하세요.

보안 참고 사항

브리지는 신뢰할 수 없을 수 있는 HTML을 Chrome 내부에서 렌더링합니다. 입력은 Chrome이 보기 전에 크기와 콘텐츠가 검증됩니다. 감싸진 문서는 default-src 'none'을 포함합니다. CDP 수준의 차단이 모든 하위 리소스 요청을 중단시킵니다. Chrome 샌드박스 플래그의 명시적 한계를 포함한 전체 전송 및 격리 모델은 /integrations/artisan/security-and-operations/ 페이지에 있습니다. 이 섹션을 완전한 보안 태세로 간주하지 마세요.

상용 컨텍스트

오픈 소스 브리지는 HTML을 PDF로 렌더링합니다. Premium 등급은 렌더링된 문서 위에 규정 준수 전자 인보이스 삽입(Pro)과 검증(Enterprise)을 더합니다. 해당 등급이 설치되지 않은 경우 EInvoiceServiceFactory는 null을 반환하므로, 오픈 소스 경로는 해당 등급 없이도 완전히 작동합니다.

참고 항목

설치 — /integrations/artisan/install/
구성 — /integrations/artisan/configuration/
빠른 시작 — /integrations/artisan/quickstart/
Chrome 렌더러 설정 — /integrations/artisan/chrome-renderer-setup/
보안 및 운영 — /integrations/artisan/security-and-operations/
프로덕션 사용 — /integrations/artisan/production-usage/