mPDF에서 NextPDF로 마이그레이션

한눈에 보기

이 가이드는 mPDF 기반 코드베이스를 NextPDF 코어로 이전하는 방법을 설명합니다. mPDF의 핵심 동사는 WriteHTML()이며, 이는 Document::writeHtml()에 직접 매핑됩니다. 핵심 작업은 생성자 구성 배열 맵(mPDF는 new Mpdf([...])에 전달하는 하나의 연관 배열로 모든 것을 구성합니다)과 글꼴 처리 차이입니다. NextPDF와 mPDF는 독립적인 엔진이므로, 마이그레이션된 문서는 mPDF 출력과 호환되지만 바이트 단위로 동일하지는 않습니다. 이 가이드는 동사 맵, 구성 배열 맵, 글꼴 차이, CSS 지원 차이, 동작 차이, 안전한 순서를 다룹니다.

이 CSS 지원 매트릭스는 어떤 HTML/CSS 기능이 검증되었는지 보여 주는 권위 있는 출처입니다. 이 가이드는 동작을 설명하며, mPDF와의 시각적 동등성을 주장하지 않습니다.

설치

composer require nextpdf/core:^3

전환 기간에는 mpdf/mpdf를 설치된 상태로 유지하십시오. 최종 전환 후 제거하십시오(안전한 마이그레이션 순서 참조).

개념 개요

mPDF의 Mpdf 객체는 하나의 큰 파사드입니다. 생성자 배열이 이를 구성하고, WriteHTML()와 페이징 동사(AddPage, SetHTMLHeader, SetHTMLFooter)가 이를 구동합니다. NextPDF는 구성을 불변 NextPDF\Core\Config 값 객체로 분리하고, Document::writeHtml()로 콘텐츠를 처리합니다. 생성자 “모드” 문자열은 없습니다. NextPDF는 전달한 HTML을 파싱한 다음, save(), output(), 또는 getPdfData()로 문서를 내보냅니다.

글꼴: mPDF는 글꼴 디렉터리와 함께 fontdata 맵과 “코어 글꼴” 폴백 세트를 제공합니다. NextPDF는 단일 글꼴 디렉터리와 CSS font-family 매칭을 통해 글꼴을 해석하며, 임베드된 글꼴을 항상 서브셋합니다(ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). 글꼴 matching/fallback은 엔진별로 다르므로(CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), 글리프 치환이 달라질 수 있습니다. 이것이 가장 눈에 띄는 주된 차이이며, 글꼴 처리 차이에서 다룹니다.

API 표면

NextPDF의 HTML API는 Html 모듈 레퍼런스입니다. 핵심 진입점은 다음과 같습니다: Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, 그리고 NextPDF\Core\Config 값 객체.

API 동사 매핑

아래 mPDF 공개 메서드 이름은 업스트림 공개 저장소(mpdf/mpdf, development)를 기준으로 확인되었습니다 — 저장소 내 _source-sidecar-upstream-api.md 출처 사이드카를 참조하십시오. 업스트림 문서 텍스트는 재현하지 않습니다.

mPDF	NextPDF	비고
`new Mpdf([...])`	`Document::createStandalone($config)`	mPDF 구성 배열은 `NextPDF\Core\Config`에 매핑됩니다. 구성 맵을 참조하십시오. 장기 실행 워커에는 `DocumentFactory`를 사용하십시오.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	직접 매핑됩니다. mPDF의 두 번째 `$mode` 인수(전체 문서 vs. CSS 전용 vs. 요소)에는 NextPDF 대응물이 없습니다 — 완전한 HTML을 전달하십시오.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	위치/크기가 지정된 HTML 영역. x/y/width/height 인수를 매핑하십시오.
`$mpdf->AddPage(...)`	`$doc->addPage()`	mPDF의 호출별 orientation/format/여백 재정의는 NextPDF에서 인수가 아닙니다. 대신 호출 사이에 문서 모델을 변경하십시오.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	Layout API를 통한 header/footer	mPDF 러닝 HTML 헤더는 NextPDF header/footer 메커니즘에 매핑되며, 본문 상단의 인라인 HTML에 매핑되지 않습니다.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	mPDF 대상 문자(`I`/`D`/`F`/`S`)는 `OutputDestination` 열거형(`Inline`/`Download`/file은 `save()`/string은 `getPdfData()`를 통해)에 매핑됩니다.
`$mpdf->Output('','S')`	`$doc->getPdfData()`	바이트를 반환합니다.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	파일 경로에 씁니다.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	ISO 32000-2 §14 정보 딕셔너리 / XMP에 저장됩니다(`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (보안 API)	권한은 리더 협조적이며 접근 제어가 아닙니다 — 보안 참고 사항을 참조하십시오.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

코드 샘플 — 프로덕션

이는 이 가이드의 글꼴 처리 개념을 뒷받침하는 실행 가능한 예제인 examples/04-text-and-fonts.php와 일치합니다. 명시적인 페이지 크기, 여백, 글꼴 선택을 활용하는 콘텐츠 본문을 사용합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->addPage();

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

엣지 케이스 및 주의 사항

$mode의 WriteHTML 인수. mPDF의 WriteHTML($html, $mode)(2 = CSS 전용, 1 = 요소)에는 대응물이 없습니다. 전달하는 HTML에 CSS를 인라인으로 넣으십시오. “CSS를 먼저 쓰고 본문을 쓰는” 순서는 없습니다.
AddPage별 재정의. mPDF는 AddPage()가 인수를 통해 문서 중간에 format/orientation을 변경하도록 허용합니다. NextPDF addPage()는 그러한 인수를 받지 않습니다. 모델 크기는 페이지 호출이 아니라 문서를 통해 변경됩니다.
Header/footer HTML. mPDF 러닝 헤더는 별도로 등록되는 HTML 조각입니다. 본문에 붙여 넣지 마십시오. 이를 NextPDF header/footer 메커니즘에 매핑하십시오.
글꼴 이름. mPDF는 fontdata/core-font 테이블을 통해 글꼴 이름을 정규화합니다. NextPDF는 CSS font-family를 글꼴 디렉터리와 매칭합니다. 자동으로 해석되던 mPDF 별칭에는 명시적인 @font-face/family 선언이 필요할 수 있습니다.
대상 문자. 'I'/'D'/'F'/'S'는 허용되지 않습니다. OutputDestination 열거형이나 save()/getPdfData()를 사용하십시오.

성능

writeHtml()는 단일 패스입니다(ADR-001). 최대 메모리는 유지된 DOM이 아니라 문서 크기를 따릅니다. 이 가이드 예제의 예산: wall_ms: 2000, peak_mb: 128. 긴 문서의 경우, 하나의 거대한 문자열 대신 addPage() 전반에 콘텐츠를 페이지 단위로 나누십시오. 이는 mPDF의 $mode 청킹에 적용되는 것과 같은 조언이지만, 페이지 모델을 통해 표현됩니다.

보안 참고 사항

권한은 리더 협조적입니다. SetProtection() → setEncryption()는 접근 제어가 아니라 기밀성을 제공합니다. ISO 권한 비트는 협조하는 리더에 의존합니다. 암호화를 사용자에게 접근 제어로 제시하지 마십시오.
메타데이터. SetTitle()와 문서 정보는 ISO 32000-2 §14 정보 딕셔너리 / XMP에 저장됩니다(iso32000_2_sec14#x1.x5.p5). 절대 그곳에 비밀을 저장하지 마십시오.
NextPDF는 문서 내 스크립트를 실행하지 않습니다. 여기서 이를 활성화하는 mPDF 지시문은 없습니다.

적합성

진술	사양	조항
글꼴은 embedded/subset 글꼴 프로그램으로 작성됩니다.	ISO 32000-2	§9
페이지 format/margins는 페이지 경계 박스에 매핑됩니다.	ISO 32000-2	§7
제목 / 보호 메타데이터는 정보 딕셔너리 / XMP에 저장됩니다.	ISO 32000-2	§14
글꼴 매칭 / 폴백은 엔진별로 다릅니다.	CSS Fonts 4 사양	§5.5

NextPDF는 ISO 32000-2 콘텐츠를 생성하며, mPDF와의 시각적 동일성을 주장하지 않습니다. 렌더러가 변경되면 출력을 다시 검토해야 합니다.

상업적 맥락

해당 없음. 코어는 여기서 설명하는 mPDF 마이그레이션 경로를 다룹니다.

참고 항목

마이그레이션 세부 사항(R6 필수 섹션)

대상 독자

서버 측 HTML-to-PDF에 mpdf/mpdf를 운영하는 팀. 사용 중인 표면이 new Mpdf([...]) + WriteHTML + Output(+ 선택적 header/footer)라면, 동사 매핑과 구성 맵이 이를 다룹니다.

범위

범위 내: Mpdf 생성자 구성 배열, WriteHTML/Output/AddPage, headers/footers, 글꼴, 보호, 메타데이터. 범위 외: mPDF 내부 클래스와 QR/바코드/워터마크 헬퍼 표면(이는 해당 NextPDF 모듈 — Barcode, Graphics — 에 매핑되며, 여기서는 다루지 않습니다).

호환성 맵

동작 호환성이며 드롭인 심이 아닙니다: Mpdf 클래스 심은 없습니다. 모든 호출 지점은 다시 작성해야 합니다. CSS 기능에 대한 기대치는 CSS 지원 매트릭스의 검증된 행을 기준으로 합니다.

생성자 구성 배열 맵

mPDF 구성 키는 업스트림 공개 저장소(mpdf/mpdf, development)를 기준으로 확인되었습니다. 업스트림 문서 텍스트는 재현하지 않습니다.

mPDF 구성 키	NextPDF	비고
`mode`	(대응물 없음)	mPDF의 모드 문자열(`'utf-8'`, `'c'`, `'+aCJK'`, …)은 font/script 동작을 선택합니다. NextPDF는 항상 유니코드입니다. CJK는 모드가 아니라 글꼴 선택으로 처리됩니다. 키를 삭제하십시오.
`format`	`Config->pageSize` (`PageSize` VO)	명명된 형식은 명시적인 포인트 치수가 됩니다. 배열 `[w,h]`는 `PageSize`에 매핑됩니다.
`orientation`	교체: `PageSize` width/height	방향 플래그가 없습니다. 가로 방향 = 너비 > 높이.
`default_font_size`	CSS 기본 font-size	생성자 키가 아니라 기본 스타일시트를 통해 설정하십시오.
`default_font`	CSS `font-family` / 등록된 글꼴	CSS / 글꼴 등록을 통해 기본 패밀리를 설정하십시오.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (`Margin` VO) 포인트 단위	하나의 `Margin` 값 객체이며, 그 생성자 순서는 mPDF 키 순서가 아니라 `Margin(top, right, bottom, left)`입니다(`src/ValueObjects/Margin.php`에 대해 확인하십시오).
`margin_header` / `margin_footer`	Layout API를 통한 header/footer 오프셋	생성자 키가 아니라 NextPDF header/footer 구성에 매핑하십시오.

글꼴 처리 차이

단일 글꼴 디렉터리. mPDF의 글꼴 디렉터리 목록 + fontdata 맵 + 코어 글꼴 폴백은 Config->fontsDirectory와 CSS font-family 매칭으로 통합됩니다.
항상 서브셋. NextPDF는 임베드된 글꼴을 항상 서브셋합니다(ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7). mPDF의 서브셋 플래그에는 대응물이 없으며 필요하지 않습니다.
매칭은 엔진별로 다릅니다. 글꼴 matching/fallback은 엔진별로 다릅니다(CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13). mPDF 글꼴 별칭에는 명시적인 @font-face 또는 정확한 패밀리 이름이 필요할 수 있습니다. 마이그레이션 후 글리프 렌더링의 기준을 다시 잡으십시오. 치환 차이는 결함이 아니라 예상되는 차이입니다.

동작 차이

글꼴 치환(위 참조) — 가장 눈에 띄는 주된 차이.
$mode가 WriteHTML에 없음 — 인라인 CSS를 포함한 완전한 HTML을 전달하십시오.
AddPage별 형식 재정의 없음 — 모델 크기는 문서를 통해 변경됩니다.
권한은 리더 협조적(보안 참고 사항 참조).
독립적인 레이아웃 엔진 — 밀도가 높은 콘텐츠에서는 줄 바꿈 / 페이지 나누기가 다릅니다. 시각적 차이의 기준을 다시 잡으십시오.

이는 어느 엔진의 결함도 아니라 문서화된 동작 차이입니다.

지원되지 않음 / 직접 대응물 없음

mode 생성자 문자열 — 모델링되지 않음(항상 유니코드).
각 AddPage()별 format/orientation/여백 인수 — NextPDF에서 인수가 아님.
mPDF fontdata 맵 — 글꼴 디렉터리 + CSS 매칭으로 대체됨.
mPDF의 'I'/'D'/'F'/'S' 대상 문자 — OutputDestination 열거형 + save()/getPdfData()로 대체됨.

안전한 마이그레이션 순서

패키지 nextpdf/core를 mpdf/mpdf와 함께 추가하십시오(지금은 mPDF를 유지).
위험이 낮은 문서 하나를 고르십시오. new Mpdf([...])는 구성 맵을 통해, WriteHTML/Output는 동사 맵을 통해 변환하십시오.
문서가 사용하는 글꼴을 Config->fontsDirectory에 등록하고, mPDF 별칭에 대해 명시적인 @font-face/family 선언을 추가하십시오.
동일한 입력으로 두 PDF를 생성하여 시각적으로 비교하십시오. 차이(글꼴 치환, 줄 바꿈)는 독립적인 엔진에서 예상되는 것입니다 — 문서별로 수용하십시오.
모든 header/footer HTML 을 NextPDF header/footer 메커니즘에 매핑하십시오.
위험이 가장 낮은 것부터 문서별로 반복하십시오. 마지막 전환까지 mPDF 를 설치된 상태로 유지하십시오.
최종 전환 후 mpdf/mpdf를 composer.json에서 제거하십시오.

마이그레이션 테스트

코드를 변경하기 전에 대표 문서의 mPDF 출력을 스냅샷하십시오(골든 입력이며, 바이트는 달라집니다).
마이그레이션된 문서별로, 자체 수용 검사(시각적 차이 + 텍스트 추출)를 통해 검증하십시오. NextPDF의 글꼴/HTML 동작은 examples/04-text-and-fonts.php와 examples/08-html-basic.php, 그리고 코어 tests/ Html/Font 스위트에서 검증됩니다. 마이그레이션 수용 기준은 문서별로 다르며 사용자의 책임입니다.
마이그레이션된 문서별로 회귀 테스트를 추가하십시오.

증거 / 추적성

이 페이지의 모든 NextPDF 동작 진술은 저장소 내 테스트, 예제, 소스 시그니처 또는 ADR로 뒷받침되거나, PDF 형식 속성인 경우 RAG에 고정된 ISO 32000-2 / CSS 조항(프런트 매터 citations:와 적합성 표에 있음)으로 뒷받침됩니다. mPDF 동작은 “독립적인 엔진 — 문서화된 차이를 예상”으로만 진술되며, 저장소 내 산출물이 증명하지 않는 패리티는 주장하지 않습니다.

NextPDF 동작 주장	저장소 내 증거(경로)
`WriteHTML()`는 `Document::writeHtml(string $html): static`에 직접 매핑됩니다.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)`는 `writeHtmlCell(...)`에 매핑됩니다.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` 기본 페이지는 A4 세로 방향입니다(`595.276 × 841.890 pt`).	`src/Core/Config.php` (기본 `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` 생성자 순서는 `(top, right, bottom, left)`입니다.	`src/ValueObjects/Margin.php` (승격된 프로퍼티 순서).
출력 대상은 `NextPDF\Contracts\OutputDestination` 열거형입니다. `'I'/'D'/'F'/'S'`는 허용되지 않습니다.	`src/Contracts/OutputDestination.php` (케이스 `Inline`/`Download`/`File`/`String`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
`Output('','S')` → `getPdfData()`; `Output($path,'F')` → `save($path)`.	`src/Core/Concerns/HasOutput.php` (`getPdfData()`, `save()`, `output()`).
`SetProtection()`는 `setEncryption(...)`에 매핑됩니다. 권한은 리더 협조적입니다.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (프런트 매터 `citations:`).
`SetTitle()` → `setTitle()`; 메타데이터는 정보 딕셔너리 / XMP에 저장됩니다.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (프런트 매터 `citations:`).
글꼴은 항상 서브셋된 프로그램으로 임베드됩니다.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (프런트 매터 `citations:`).
글꼴 매칭 / 폴백은 엔진별로 다릅니다(치환 차이).	CSS Fonts 4 §5.5 (프런트 매터 `citations:` + 적합성).
`writeHtml()`는 단일 패스입니다. 최대 메모리는 문서 크기를 따릅니다.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

롤백

두 패키지는 최종 전환까지 설치된 상태로 유지되므로, 호출 지점별 롤백은 해당 호출 지점을 mPDF 경로로 되돌리는 방식입니다. 최종 전환 후 롤백은 버전 관리에서 mpdf/mpdf와 이전 코드를 복원하는 방식입니다. 데이터 마이그레이션은 관여하지 않습니다.

성능 고려 사항

자세한 내용은 성능을 참조하십시오. 단일 패스 모델은 mPDF의 버퍼 유지 비용을 제거합니다. 새로운 문서별 비용은 즉시 글꼴 해석(3 단계)이며, 이는 글꼴 디렉터리를 통해 캐시할 수 있습니다.

흔한 함정

기존 mode 키를 유지하고 그것으로부터 CJK 동작을 기대하는 것(키는 삭제됩니다. CJK는 글꼴 선택입니다).
여전히 WriteHTML($html, 2)(CSS 전용 모드)를 전달하는 것 — 대신 CSS를 인라인하십시오.
header/footer HTML을 본문에 붙여 넣는 것.
명시적인 패밀리 없이 mPDF 별칭에 대해 동일한 글꼴을 기대하는 것.
byte/pixel-identical 출력을 기대하는 것(독립적인 엔진 — 이 가이드는 드롭인이나 100% 호환성을 결코 주장하지 않습니다).
CSS 지원 매트릭스를 권고 사항으로 취급하는 것 — 이는 검증된 기능에 대한 권위 있는 출처입니다.