mPDF에서 마이그레이션
이 가이드는 mPDF(mpdf/mpdf)에서 TCPDF-Next로 마이그레이션하는 것을 도와줍니다. mPDF는 CJK 텍스트, 바코드, 워터마크와 같은 기능을 갖춘 광범위한 CSS 지원의 HTML-to-PDF 라이브러리입니다. TCPDF-Next는 현대적 표준 준수와 런타임 종속성 없이 mPDF 기능의 상위 집합을 제공합니다.
기능 비교
| 기능 | mPDF | TCPDF-Next |
|---|---|---|
| PHP 버전 | 7.4+ | 8.5+ |
| PDF 버전 | PDF 1.4 / 1.7 | PDF 2.0 |
| 아키텍처 | HTML/CSS 중심 | HTML 지원이 있는 PDF 네이티브 |
| 런타임 종속성 | 10개 이상 Composer 패키지 | 없음 |
| 암호화 | RC4, AES-128, AES-256 | AES-256만 (PDF 2.0) |
| 디지털 서명 | 지원 안 됨 | PAdES B-B부터 B-LTA |
| PDF/A | PDF/A-1b, PDF/A-3b (부분) | PDF/A-4 (전체 ISO 19005-4) |
| 태그 PDF | 제한적 | 전체 PDF/UA 접근성 |
| CJK 지원 | 예 (번들 50MB 이상 폰트) | 예 (자체 등록, 최적화된 서브셋팅) |
| RTL / BiDi | 예 | 예 (UAX #9 준수) |
| 바코드 | 예 (1D 및 2D) | 예 (네이티브 벡터, 확장 세트) |
| 워터마크 | 예 | 예 |
| 목차 생성 | 예 | 예 |
| 메모리 사용량 | 높음 (전체 DOM 메모리 보유) | 보통 (스트리밍 출력) |
mPDF 전용 기능과 TCPDF-Next 동등 기능
커스텀 HTML 태그
mPDF는 비표준 HTML 태그를 정의합니다. 이들은 적응이 필요합니다:
| mPDF 커스텀 태그 | TCPDF-Next 동등 기능 |
|---|---|
<tocpagebreak> | $pdf->addTableOfContentsPage() |
<tocentry content="..." level="0"> | $toc->addEntry('...', level: 0) |
<barcode code="..." type="C128"> | $page->addBarcode(BarcodeFactory::code128('...')) |
<columnbreak> | $renderer->columnBreak() |
<pagebreak> | <div style="page-break-before: always"> (표준 CSS) |
<bookmark content="..."> | $pdf->addBookmark('...') |
<watermarktext content="DRAFT"> | $pdf->setWatermark(Watermark::text('DRAFT')) |
<watermarkimage src="..."> | $pdf->setWatermark(Watermark::image('...')) |
HTML 머리글 및 바닥글
mPDF (이전):
php
$mpdf->SetHTMLHeader('<div style="text-align: center;">Header</div>');
$mpdf->SetHTMLFooter('<div>Page {PAGENO} of {nbpg}</div>');
$mpdf->SetHTMLHeader('<div>Even header</div>', 'E');TCPDF-Next (이후):
php
$pdf->setHtmlHeader('<div style="text-align: center;">Header</div>');
$pdf->setHtmlFooter('<div>Page {{pageNumber}} of {{totalPages}}</div>');
$pdf->setHtmlHeader('<div>Even header</div>', pages: 'even');WriteHTML 모드
mPDF (이전):
php
$mpdf->WriteHTML($css, \Mpdf\HTMLParserMode::HEADER_CSS);
$mpdf->WriteHTML($body, \Mpdf\HTMLParserMode::HTML_BODY);TCPDF-Next (이후):
php
$renderer = new HtmlRenderer($pdf);
$renderer->addStylesheet($css);
$renderer->writeHtml($body);워터마크
mPDF (이전):
php
$mpdf->SetWatermarkText('DRAFT', 0.1);
$mpdf->showWatermarkText = true;TCPDF-Next (이후):
php
$pdf->setWatermark(
Watermark::text('DRAFT')
->setOpacity(0.1)
->setRotation(45)
->setColor(Color::rgb(200, 200, 200))
);구성 매핑
| mPDF 구성 | TCPDF-Next 동등 기능 |
|---|---|
mode => 'utf-8' | 항상 UTF-8 (구성 불필요) |
format => 'A4' | setPageFormat(PageFormat::A4) |
margin_left/right/top/bottom | setMargins(new Margins(...)) |
default_font | $renderer->setDefaultFont(...) |
tempDir | PdfDocument::create()->setTempDir(...) |
autoScriptToLang | $renderer->setAutoFontDetection(true) |
biDirectional | 항상 활성화 (UAX #9) |
pdfaAuto | setPdfALevel(PdfALevel::PDF_A_4) |
출력 메서드
mPDF (이전):
php
$mpdf->Output('/path/to/file.pdf', \Mpdf\Output\Destination::FILE);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::DOWNLOAD);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::INLINE);
$content = $mpdf->Output('', \Mpdf\Output\Destination::STRING_RETURN);TCPDF-Next (이후):
php
$pdf->save('/path/to/file.pdf');
$bytes = $pdf->toString();
// 웹 응답 (Laravel 예제)
return response($pdf->toString(), 200, [
'Content-Type' => 'application/pdf',
'Content-Disposition' => 'attachment; filename="doc.pdf"',
]);종속성 감소
mPDF에서 마이그레이션하면 종속성 트리가 크게 단순화됩니다:
제거됨 (mPDF + 전이적):
mpdf/mpdf+ 10개 이상의 전이적 패키지psr/log,psr/http-message,setasign/fpdi,mpdf/qrcode
추가됨:
yeee-fang/tcpdf-next(런타임 종속성 없음)
성능 비교
| 지표 | mPDF | TCPDF-Next | 개선 |
|---|---|---|---|
| 간단한 1페이지 PDF | 45.3 ms | 8.2 ms | 5.5배 빠름 |
| 100페이지 문서 | 3,210 ms | 845 ms | 3.8배 빠름 |
| 피크 메모리 (1페이지) | 18.4 MB | 4.2 MB | 4.4배 적음 |
| 피크 메모리 (100페이지) | 198.2 MB | 28.6 MB | 6.9배 적음 |
| 출력 파일 크기 (1페이지) | 24.3 KB | 12.4 KB | 2.0배 작음 |
전체 방법론과 테스트 케이스는 성능 벤치마크를 참조하세요.
더 읽을거리
- API 매핑 테이블 — 포괄적인 메서드 매핑
- 벤치마크 — mPDF와의 전체 성능 비교
- API 레퍼런스 — 전체 TCPDF-Next API 문서
- FAQ — 일반적인 마이그레이션 질문