마이그레이션 가이드
마이그레이션 가이드
섹션 제목: “마이그레이션 가이드”NextPDF는 PHP용 PDF 2.0 엔진입니다. 이미 다른 라이브러리로 PDF를 생성하고 있다면, 마이그레이션 가이드가 해당 라이브러리의 API를 NextPDF에 매핑하고 마주할 동작 차이를 문서화합니다. 이 페이지는 저장소 간 인덱스입니다. 어떤 가이드가 어느 라이브러리에서의 이동을 다루는지, 어느 저장소가 각 가이드를 소유하는지, 모든 가이드가 공유하는 하나의 모델을 기록합니다.
이 페이지는 인덱스이므로 어떤 가이드에 대해서도 동작 관련 주장을 하지 않습니다. 각 가이드는 자체 저장소가 소유합니다. 애그리게이터가 이를 이 사이트로 가져오며, 가이드가 추가되기 전까지 아래 링크는 자리표시자를 가리킵니다. 모든 동작 관련 주장은 가이드 자체에 있으며, 저장소 내 테스트 또는 고정된 ISO 32000-2 / CSS WG 조항으로 뒷받침되고 이 페이지에는 포함되지 않습니다.
하나의 마이그레이션 모델
섹션 제목: “하나의 마이그레이션 모델”모든 NextPDF 마이그레이션 가이드는 하나의 정직한 모델을 공유합니다. 각 가이드는 이 모델을 염두에 두고 읽어야 합니다.
- 호환되지만 byte-identical은 아닙니다. NextPDF와 사용을 중단하는 라이브러리는 독립적인 구현입니다. 마이그레이션한 문서는 의도 측면에서 기능적으로 동등하지만, pixel이나 byte 단위로 동일하지는 않습니다. 어떤 가이드도 드롭인 교체나 100% 호환성을 주장하지 않습니다.
- 커버리지는 측정된 개수이며, 단언이 아닙니다. 가이드가 커버리지 수치를 명시하는 경우(예: TCPDF 어댑터), 그 수치는 ISO/IEC 25023 43항의 의미에서 저장소 내 매트릭스로부터 도출된 기능 완전성 메트릭입니다. 즉, 포괄적 보증이 아니라 커버된 메서드의 측정된 개수입니다.
- 각 가이드는 동작 차이를 공개적으로 명시합니다. 모든 가이드는 명시적인 차이점 표와 “지원되지 않음 / 직접적인 대응 항목 없음” 섹션을 포함합니다. 차이는 결함이 아니라 문서화된 엔진 속성입니다.
- 렌더러 변경에는 재검토가 필요합니다. 마이그레이션은 코드 변경에 더해 출력 기준선 재설정을 포함합니다. 각 가이드는 마이그레이션을 테스트하는 방법을 설명합니다. 시각적 승인은 문서별로 이루어지며 통합 담당자의 책임입니다.
마이그레이션 형태
섹션 제목: “마이그레이션 형태”가이드는 두 가지 형태로 나뉩니다. 형태는 코드가 얼마나 바뀌는지를 알려줍니다.
- API 재작성 마이그레이션에는 호환성 심이 없습니다. 모든 호출 위치가 가이드의 동사 매핑과 옵션 맵을 사용하여 재작성됩니다. HTML-to-PDF 라이브러리 마이그레이션(
dompdf,mpdf)이 이 형태이며, NextPDF Html 파이프라인을 직접 대상으로 합니다. - 드롭인 후 마이그레이션 방식은 소스 수준에서 거의 호환되는 어댑터를 제공하므로, 초기 이동은 최소한의 의존성 교체로 이루어집니다. 그 후 호출 위치를 최신 API로 점진적으로 마이그레이션한 다음 어댑터를 폐기합니다. TCPDF 마이그레이션은
nextpdf/compat-legacy어댑터를 통한 이 형태입니다.
가이드 및 소유 저장소 참조
섹션 제목: “가이드 및 소유 저장소 참조”아래의 모든 가이드는 소유 저장소의 docs/public/에 있으며, 애그리게이터가 이를 이 사이트로 가져옵니다. 해당 가이드의 동작 관련 주장에 대한 권위는 소유 저장소에 있습니다. 이 인덱스는 라우팅만 기록합니다.
| 출발 라이브러리 | 가이드 | 형태 | 소유 저장소 | 페이지 |
|---|---|---|---|---|
| Dompdf | Dompdf → NextPDF Html 파이프라인 | API 재작성 | nextpdf (core 에디션) | Dompdf 가이드 dompdf (업스트림 예정) |
| mPDF | mPDF → NextPDF core 에디션 | API 재작성 | nextpdf (core 에디션) | mPDF 가이드 mpdf (업스트림 예정) |
| TCPDF 6.x | TCPDF → compat-legacy 어댑터를 통한 NextPDF | 드롭인 후 마이그레이션 | nextpdf-compat-tcpdf 저장소, 패키지 nextpdf/compat-legacy | TCPDF 가이드 tcpdf-compat (업스트림 예정) |
앞서 언급한 dompdf 및 mpdf 가이드는 core 엔진 API를 대상으로 하므로 core 저장소에 있으며, core examples/가 이를 뒷받침합니다. tcpdf-compat 가이드는 compat-tcpdf 저장소에 있는데, 이는 nextpdf/compat-legacy 패키지가 TCPDF 동작 표면과 가이드를 뒷받침하는 어댑터 테스트를 소유하기 때문입니다. 이 인덱스는 여러 저장소에 걸쳐 있으므로 문서 네이티브 형태로 존재하며, 그 어느 것에 대해서도 동작 관련 주장을 하지 않습니다.
각 가이드의 용도
섹션 제목: “각 가이드의 용도”- Dompdf → NextPDF (
dompdf(업스트림 예정)) — 서버 측에서dompdf/dompdf를 사용하는 코드베이스를 위한 것입니다.loadHtml/render/output와Options키를 NextPDF Html 파이프라인에 매핑하며, CSS 기능 기대치는 Verified 전용 CSS 지원 매트릭스에 위임합니다. Dompdf 클래스 심은 없습니다. 모든 호출 위치가 재작성됩니다. - mPDF → NextPDF (
mpdf(업스트림 예정)) —mpdf/mpdf를 사용하는 코드베이스를 위한 것입니다.WriteHTML/Output/AddPage와 생성자 구성 배열을 core API에 매핑하며, 글꼴 처리에는 차이가 있습니다. NextPDF는 단일 글꼴 디렉터리와 CSS 매칭을 통해 해석하며 항상 서브셋을 만듭니다. Mpdf 클래스 심은 없습니다. - TCPDF → NextPDF (compat-legacy) (
tcpdf-compat(업스트림 예정)) — 초기 변경을 최소화하려는 TCPDF 6.x 코드베이스를 위한 것입니다. 어댑터를 설치하고, strict 모드로 저장소 내 커버리지 매트릭스를 기준으로 실제 사용 표면을 감사한 다음, 호출 위치를 어댑터에서 마이그레이션하고, 그 위에 PDF/UA-2 태그 구조를 추가하세요. 이는 TCPDF에는 결코 없었던 기능입니다. 어댑터는 발판이며, 최종 목적지가 아니고 드롭인 보증도 아닙니다.
가이드 링크가 해석되는 방식
섹션 제목: “가이드 링크가 해석되는 방식”위의 각 [[…]] 자리표시자는 소유 저장소의 docs/public/migration/ 아래에 있는 페이지를 가리키는 전방 참조이며, 애그리게이터가 해당 페이지를 이 사이트로 가져옵니다. 대상 슬러그는 하나의 규칙을 따릅니다:
/migration/<source>/위 <source> 토큰은 마이그레이션 출발 라이브러리의 짧은 이름이며, 위의 가이드 참조 표에 나열된 대로 dompdf, mpdf, tcpdf-compat 중 하나입니다. 대상 페이지가 집계되기 전까지 해당 링크는 자리표시자이며 해석되지 않습니다. 이 인덱스는 어떤 대상 가이드에 대해서도 동작 관련 주장을 하지 않습니다. 라우팅과 공유 마이그레이션 모델만 기록합니다.
참고 자료
섹션 제목: “참고 자료”- CSS 지원 매트릭스 —
dompdf및mpdf가이드가 CSS 기능 기대치를 위임하는 Verified 전용 권위 자료입니다. - 통합 쿡북 — 에코시스템 통합 패키지를 위한 저장소 간 인덱스입니다(이는 엔진으로 마이그레이션하는 일이 아니라 엔진을 연결하는 일이라는 별도의 관심사입니다).