DomPDF에서 마이그레이션
이 가이드는 DomPDF(dompdf/dompdf)에서 TCPDF-Next로 마이그레이션하는 것을 도와줍니다. 두 라이브러리는 근본적으로 다른 설계 철학을 가지고 있습니다 — DomPDF는 HTML/CSS를 PDF로 변환하는 렌더러인 반면, TCPDF-Next는 강력한 HTML 렌더링 엔진을 갖춘 PDF 네이티브 라이브러리입니다.
DomPDF 접근 방식 vs TCPDF-Next 접근 방식
DomPDF는 PDF 생성을 HTML 렌더링으로 취급합니다. HTML과 CSS를 작성하면 DomPDF가 이를 PDF로 변환합니다. 편리하지만 CSS가 표현할 수 있는 것으로 제한되며, 디지털 서명, 암호화, PDF/A 규정 준수와 같은 네이티브 PDF 기능에 접근할 수 없습니다.
TCPDF-Next는 두 가지 접근 방식을 제공합니다:
| 접근 방식 | 설명 | 적합한 경우 |
|---|---|---|
| Core API | PHP 메서드를 통한 직접 PDF 구성 | 정밀 레이아웃, 폼, 그래픽, 서명 |
| Artisan HTML 렌더러 | DOM 기반 HTML/CSS 렌더러(HtmlRenderer) | HTML 중심 콘텐츠, DomPDF에서 마이그레이션 |
대부분의 DomPDF 마이그레이션에는 Artisan HTML 렌더러를 사용하세요 — 최소한의 변경으로 기존 HTML 템플릿을 받아들입니다.
API 매핑
| DomPDF | TCPDF-Next | 비고 |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | 플루언트 빌더 |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | 동일한 HTML 동작 |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | 기본적으로 로컬 파일만 |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | Enum 기반 |
$dompdf->render() | save() / toString()에서 자동 | 명시적 렌더 단계 없음 |
$dompdf->output() | $pdf->toString() | 바이너리 문자열 반환 |
$dompdf->stream('file.pdf') | 프레임워크 응답 헬퍼 | 아래 예제 참조 |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | 명시적 허용 목록 |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | 더 세분화된 제어 |
기본 마이그레이션 예제
DomPDF (이전):
php
use Dompdf\Dompdf;
use Dompdf\Options;
$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);
$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());TCPDF-Next (이후):
php
use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;
$pdf = PdfDocument::create()
->setPageFormat(PageFormat::A4)
->build();
$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);
$pdf->save('output.pdf');CSS 지원 비교
| CSS 기능 | DomPDF | TCPDF-Next |
|---|---|---|
| 박스 모델 (margin, padding, border) | 예 | 예 |
| Float | 부분 | 부분 |
| Flexbox | 아니요 | 아니요 |
| Grid | 아니요 | 아니요 |
position: absolute/relative | 부분 | 예 |
@font-face | 예 | 예 |
page-break-before/after | 예 | 예 |
background-image | 부분 | 예 |
border-radius | 아니요 | 예 |
opacity | 예 | 예 |
CSS 변수 (--custom) | 아니요 | 아니요 |
| 미디어 쿼리 | 아니요 | @media print만 |
table 레이아웃 | 예 | 예 (향상됨) |
TIP
TCPDF-Next의 HTML 렌더러는 대부분의 CSS 2.1 속성과 선택적 CSS 3 속성을 지원합니다. Flexbox와 Grid는 지원되지 않습니다 — 복잡한 레이아웃에는 테이블을 사용하세요. CSS 렌더링 차이가 발견되면 HTML 렌더러 문서를 확인하세요.
Core vs Artisan 사용 시기
| 시나리오 | 권장 접근 방식 |
|---|---|
| 기존 HTML 템플릿 마이그레이션 | Artisan HTML 렌더러 |
| 픽셀 퍼펙트 레이아웃 (인보이스, 인증서) | Core API |
| 디지털 서명 필요 | Core API (서명은 양쪽 모두 동작하지만, Core가 더 많은 제어 가능) |
| PDF/A 규정 준수 | 둘 다 (양쪽 모두 PDF/A-4 지원) |
| 바코드 / QR 코드 | Core API (네이티브 벡터 렌더링) |
| 입력 가능한 폼 필드 | Core API |
| HTML의 간단한 리포트 | Artisan HTML 렌더러 |
성능 비교
| 지표 | DomPDF | TCPDF-Next | 개선 |
|---|---|---|---|
| 간단한 1페이지 PDF | 62.1 ms | 8.2 ms | 7.6배 빠름 |
| 20페이지 리포트 | 891 ms | 187 ms | 4.8배 빠름 |
| 피크 메모리 (1페이지) | 22.1 MB | 4.2 MB | 5.3배 적음 |
| 피크 메모리 (20페이지) | 89.7 MB | 12.4 MB | 7.2배 적음 |
| 출력 파일 크기 (1페이지) | 31.8 KB | 12.4 KB | 2.6배 작음 |
자세한 방법론과 추가 테스트 케이스는 성능 벤치마크를 참조하세요.
마이그레이션 후 새로운 기능
DomPDF가 지원하지 않는 TCPDF-Next에서 사용 가능한 기능:
- 디지털 서명 — 하드웨어 보안 모듈 지원이 있는 PAdES B-B부터 B-LTA.
- AES-256 암호화 — 비밀번호 및 인증서 기반 문서 보호.
- PDF/A-4 — 전체 아카이브 규정 준수 (ISO 19005-4).
- 태그 PDF / PDF/UA — 스크린 리더를 위한 접근성.
- 네이티브 바코드 — QR, Data Matrix, Code 128, EAN 등을 벡터 그래픽으로.
- 폼 필드 — 입력 가능한 텍스트 필드, 체크박스, 드롭다운.
- 교차 참조 스트림 — 현대적 PDF 구조로 더 작은 파일 크기.
더 읽을거리
- API 매핑 테이블 — 상세 메서드 매핑
- 벤치마크 — 전체 성능 비교
- 보안 개요 — DomPDF 대비 보안 개선 사항
- API 레퍼런스 — 전체 TCPDF-Next API 문서