Artisan 패키지

Artisan · LGPL-3.0

Artisan 패키지(yeeefang/tcpdf-nextartisan)는 Chrome DevTools Protocol(CDP)을 기반으로 한 픽셀 퍼펙트 HTML-to-PDF 변환을 제공합니다. Flexbox, Grid, 웹 폰트, 미디어 쿼리, 렌더링 시점에 고정된 애니메이션을 포함한 완전한 CSS3 지원으로 HTML을 렌더링합니다.

Artisan 사용 시기

시나리오	권장
HTML/CSS 템플릿에서 PDF 생성	Artisan
프로그래밍 방식의 PDF 구성 (셀, 그리기)	Core
HTML 이메일을 PDF 보관	Artisan
구조화된 데이터에서 송장 생성	Core 또는 Artisan
복잡한 CSS 레이아웃 (Grid, Flexbox)	Artisan
서명/암호화된 PDF	Core

작동 방식

Artisan은 Chrome DevTools Protocol을 통해 헤드리스 Chrome 인스턴스를 실행하고, HTML 콘텐츠를 브라우저 페이지에 로드한 다음, Chrome의 내장 PDF 인쇄 기능을 사용합니다. 이는 Chrome이 지원하는 모든 CSS 기능을 PDF에 사용할 수 있음을 의미합니다 -- 제한된 CSS 파서와 씨름할 필요가 없습니다.

HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / stream

설치

composer require yeeefang/tcpdf-nextartisan

요구 사항:

• PHP 8.2+
• chrome-php/chrome ^1.15 (자동 설치)
• 호스트에 Chrome 또는 Chromium 브라우저 설치

# Ubuntu/Debian
apt-get install -y chromium-browser

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# 환경 변수를 통해 사용자 정의 경로 설정
export CHROME_PATH=/usr/bin/google-chrome

빠른 시작

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
    ->save('/output/hello.pdf');

URL에서

HtmlRenderer::create()
    ->loadUrl('https://example.com/report')
    ->save('/output/report.pdf');

파일에서

HtmlRenderer::create()
    ->loadFile('/templates/invoice.html')
    ->save('/output/invoice.pdf');

패키지 구성

클래스	용도
HtmlRenderer	주요 진입점 -- HTML 로드, 구성, 렌더링
ChromeBridge	Chrome DevTools Protocol 통신
RenderOptions	렌더링 구성 (여백, 스케일, 헤더)
PageSetup	렌더링을 위한 페이지 크기 및 방향
PdfMerger	여러 렌더링된 페이지를 단일 PDF로 병합
StyleInjector	렌더링 전 CSS 스타일시트 주입
ScreenshotCapture	페이지 스크린샷 캡처 (PNG/JPEG)

예외 계층 구조

예외	발생 시점
RenderException	일반적인 렌더링 실패
ChromeNotFoundException	예상 경로에서 Chrome 바이너리를 찾을 수 없음
TimeoutException	페이지 로드 또는 렌더링이 구성된 타임아웃 초과

모든 예외는 Yeeefang\TcpdfNext\Artisan\Exceptions 네임스페이스에 있으며 공통 ArtisanException 기본 클래스를 확장합니다.

Core HTML 파서와의 비교

Core 패키지에는 기본 HTML-to-PDF 변환을 위한 HtmlParser 모듈이 포함되어 있습니다. 종속성이 없는 솔루션이 필요한 경우 사용하십시오. 완전한 브라우저 렌더링 충실도가 필요한 경우 Artisan을 사용하십시오.

기능	Core HtmlParser	Artisan
외부 종속성	없음	Chrome/Chromium
CSS Flexbox / Grid	아니오	예
웹 폰트 (@font-face)	아니오	예
미디어 쿼리	아니오	예
JavaScript 실행	아니오	예
@page CSS 규칙	아니오	예
성능 (간단한 문서)	더 빠름	더 느림
성능 (복잡한 CSS)	N/A	안정적

다음 단계

• HTML 렌더러 -- HTML 콘텐츠 로드 및 렌더링.
• 렌더링 옵션 -- 페이지 크기, 여백, 헤더, 푸터 구성.
• 고급 기능 -- PDF 병합, CSS 주입, 스크린샷.
• Docker 설정 -- 컨테이너에서 Artisan 실행.