NextPDF compat-legacy의 TCPDF 메서드 커버리지
한눈에 보기
섹션 제목: “한눈에 보기”nextpdf/compat-legacy는 호환성 계층이며, TCPDF의 포크나 동작이 보장되는 복제본이 아닙니다. TCPDF 6.x의 public 메서드 이름, 매개변수 순서, 기본값을 NextPDF 코어 엔진 위에 노출합니다. 대부분의 호출은 NextPDF Document 작업으로 직접 매핑됩니다. 일부 지정된 메서드는 NextPDF가 따르지 않는 레거시 매개변수를 받아들이거나 아무런 효과가 없습니다.
이 페이지는 메서드별 감사 결과를 읽기 쉽게 요약합니다. 권위 있고 테스트로 검증된 커버리지 매트릭스는 저장소의 docs/TCPDF_COVERAGE.md에 있습니다. 이 페이지와 저장소 내 매트릭스가 일치하지 않을 경우, 테스트 스위트가 단언하는 저장소 내 매트릭스가 우선합니다.
마이그레이션하기 전에 이 페이지로 한 가지 질문에 답하십시오: 내 코드베이스가 호출하는 모든 TCPDF 메서드에 대해 어댑터는 실제로 무엇을 하는가?
커버리지 요약
섹션 제목: “커버리지 요약”이 감사는 약 120개의 TCPDF 6.x public 메서드를 조사했습니다. 각 메서드는 네 가지 범주 중 정확히 하나로 분류되었습니다.
| 범주 | 개수 | 사용자에게 의미하는 것 |
|---|---|---|
| 미러링 — 완전 위임 | 94 | 호출이 NextPDF Document 메서드로 직접 매핑됩니다. 문서화된 매개변수에서는 동작이 호환됩니다. |
| 무음 무시 — 부분 | 15 | 메서드는 실행되어 출력을 만들지만, 하나 이상의 TCPDF 매개변수가 아무런 효과를 내지 않습니다. 문서화된 동작 차이입니다. |
| 미구현 — 빈 본문 | 4 | 메서드는 소스 호환성을 위해 존재하지만 아무것도 하지 않습니다. |
| 해당 없음 | 7 | 해당 TCPDF 메서드는 PDF 출력에 영향을 주지 않아 의도적으로 제외되었습니다. |
| 추가된 모던 API 드리프트 메서드 | 17 | 혼합 API 코드가 컴파일되도록 어댑터에 노출된 NextPDF v5.1+ Document 메서드입니다. TCPDF 6.x에는 해당하는 항목이 없습니다. |
이 수치는 docs/TCPDF_COVERAGE.md §Summary에서 가져온 것입니다. 매트릭스는 tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php 및 tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php로 검증됩니다.
표현상의 주의. 이 패키지는 “드롭인 교체품” 또는 “100% TCPDF 호환”이라고 주장하지 않습니다. 조사된 약 120개의 TCPDF 메서드 중 94개를 직접 위임으로 다룹니다. 나머지 메서드는 아래에 설명된 문서화된 동작 차이가 있습니다. 더 정확한 설명은 알려지고 테스트된 호환성 표면을 가진 TCPDF 호환 대안입니다.
메서드 개수에 관한 주의
섹션 제목: “메서드 개수에 관한 주의”어댑터는 25개의 단일 책임 concern 트레이트(src/Compat/Tcpdf/Concerns/)로 구성되며, 총 273개의 public 메서드를 노출합니다. 또한 TCPDF 클래스 자체에도 소수의 라이프사이클 및 이스케이프 해치 메서드가 있습니다. 위의 커버리지 범주는 어댑터의 전체 public 메서드 개수가 아니라, 서로 다른 TCPDF 6.x API 표면 메서드(약 120개)를 셉니다. 두 숫자는 서로 다른 것을 측정합니다: API 표면 커버리지와 구현 규모입니다. 패키지 README.md에 더 적은 트레이트 수나 메서드 수가 인용되어 있다면, docs/TCPDF_COVERAGE.md와 이 페이지를 권위 있는 기준으로 취급하십시오 — README 요약은 AdaptsDriftV51 트레이트가 추가되기 전 기준입니다.
1. 미러링 메서드 — 호환 위임
섹션 제목: “1. 미러링 메서드 — 호환 위임”94개의 메서드가 기반 NextPDF\Core\Document 인스턴스에 직접 매핑됩니다. 엔진에서 camelCase를 사용하는 경우 PascalCase TCPDF 이름은 camelCase NextPDF 이름으로 매핑됩니다. 어댑터는 순방향 및 역방향 호환성을 위해 두 표기를 모두 받아들입니다.
대표 그룹(전체 표: docs/TCPDF_COVERAGE.md §1):
| TCPDF 영역 | 예시 메서드 | 어댑터 트레이트 |
|---|---|---|
| 라이프사이클 | Output(), Close(), getPDFData() | AdaptsLifecycle |
| 페이지 | AddPage(), getNumPages(), deletePage() | AdaptsPageManagement |
| 텍스트 | Cell(), MultiCell(), Write(), Text(), Ln() | AdaptsTextOutput |
| 폰트 | SetFont(), SetFontSize(), AddFont() | AdaptsFonts |
| 색상 | SetTextColor(), SetDrawColor(), SetFillColor() | AdaptsColors |
| 그리기 | Line(), Rect(), Circle(), Polygon(), Arrow() | AdaptsDrawing |
| 변환 | Rotate(), Scale(), Translate(), Skew(), Mirror*() | AdaptsTransforms |
| 내비게이션 | AddLink(), Annotation(), addTOC() | AdaptsNavigation |
이 메서드들의 관찰된 동작은 NextPDF가 문서화한 매개변수 범위에서 TCPDF 6.x와 호환됩니다. 어댑터는 PDF 출력이 바이트 단위로 동일하다고 단언하지 않습니다. 기반 엔진은 독립적인 PDF 2.0 구현이므로 보이는 결과가 같더라도 렌더링된 바이트는 다릅니다. 테스트가 렌더링된 콘텐츠가 아니라 정확한 PDF 바이트를 단언한다면, 해당 단언은 재기준화해야 할 가능성이 높습니다. 권장 재기준화 전략은 /integrations/tcpdf-compat/migration/을 참조하십시오.
2. 무음 무시 메서드 — 문서화된 동작 차이
섹션 제목: “2. 무음 무시 메서드 — 문서화된 동작 차이”이 15개의 메서드는 실행되어 출력을 생성하지만, 적어도 하나의 TCPDF 매개변수를 소스 호환성을 위해 받아들인 뒤 무시합니다. 이는 마이그레이션 전에 반드시 읽어야 하는 가장 중요한 단일 섹션입니다. 호출이 실패하지 않고 조용히 TCPDF 원본보다 적은 일을 하기 때문입니다.
| TCPDF 메서드 | 무시되는 매개변수 | 호환 대안 |
|---|---|---|
Image() | type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs | NextPDF image()는 file, x, y, width, height를 받습니다. 클릭 가능한 이미지에는 이미지를 그린 뒤 동일한 사각형 위에 Document::link()를 추가하십시오. 이미지 마스킹과 대체 이미지는 지원되지 않습니다. |
writeHTML() | ln, fill, reseth, cell, align | NextPDF writeHtml()는 콘텐츠만 처리합니다. 레이아웃 제어가 필요하면 모던 API를 통해 HTML을 위치 지정된 블록으로 감싸십시오. |
writeHTMLCell() | border (string form), ln, fill, reseth, autopadding | 너비, 높이, 위치, 불리언 border는 따르지만, 더 풍부한 셀 레이아웃에는 매핑이 없습니다. |
ImageEps() | link, useBoundingBox, align, palign, border, fitonpage, fixoutvals | 위치와 크기만 적용됩니다. |
ImageSVG() | link, align, palign, border, fitonpage | 위치와 크기만 적용됩니다. |
SetProtection() | mode (non-zero), pubkeys (non-empty) | NextPDF는 표준 핸들러에 항상 AES-256을 사용합니다. 인증서 기반 암호화에는 어댑터에 노출된 모던 setPublicKeyEncryption()를 사용하십시오(/integrations/tcpdf-compat/security-and-operations/ 참조). |
Bookmark() | style, color, x, isNamedDest | 제목, 레벨, y 위치만 따릅니다. |
setDestination() | page, x | 이름과 y 위치만 따릅니다. |
Link() | spaces | TCPDF의 내부 공백 추적 값이며, 엔진에 해당하는 항목이 없습니다. |
Annotation() | Subtype 외 옵션 키, spaces | 유형, 위치, 텍스트는 따릅니다. |
SetLineStyle() | width 외 대시 패턴 세부 사항 | 핵심 선 속성은 매핑됩니다. |
setAlpha() | 부분적인 블렌드 모드 매핑 | 일부 블렌드 모드 이름은 엔진에 대응 항목이 없습니다. |
Polycurve() | 전체 매개변수 목록 | 기본 모드에서는 동작 없음(no-op)이며, 엔진에 해당하는 항목이 없습니다. |
PieSectorXY() | 전체 매개변수 목록 | 부분 매핑(중심-테두리 선이 다름). |
RoundedRectXY() | 모서리별 반경 | 균일한 모서리 반경만 적용됩니다. |
어댑터가 이러한 차이를 드러내는 방식은 엄격 모드(strict mode) 설정에 따라 달라집니다(/integrations/tcpdf-compat/configuration/ 참조). 엄격 모드가 꺼져 있으면(하위 호환 기본값), 이러한 호출은 조용히 저하됩니다. 엄격 모드가 켜져 있으면, 매개변수를 무시하는 호출마다 무시된 매개변수의 정확한 목록과 마이그레이션 힌트가 담긴 TcpdfNotImplementedException을 던집니다. 엄격 모드는 감사 도구이며 프로덕션 설정이 아닙니다.
엄격 모드 설계는 호출자가 자신의 의도가 반영되지 않았을 때 이를 관찰할 수 있어야 한다는 원칙을 따릅니다. OWASP ASVS 5.0 §16.5.3은 애플리케이션이 우아하고 안전하게 실패하며 fail-open 조건을 방지해야 한다고 명시합니다. 무음 매개변수 손실은 취약점이라기보다 개발자 경험상의 함정에 가깝지만, 동일한 명시적 실패 원칙이 적용됩니다. 고정된 절(clause) 다이제스트는 페이지 프런트매터
citations에 있습니다.
3. 미구현 메서드 — 빈 본문(no-op)
섹션 제목: “3. 미구현 메서드 — 빈 본문(no-op)”레거시 소스가 컴파일되도록 네 개의 메서드가 존재하지만, 그 본문은 아무것도 하지 않습니다. 엄격 모드가 켜져 있으면 그중 세 개는 TcpdfNotImplementedException을 던집니다. 네 번째(Open())는 레거시 코드에서 제거해도 항상 안전하므로, 결코 던지지 않는 의도적인 안전한 no-op입니다.
| TCPDF 메서드 | 동작 | 대체 |
|---|---|---|
setSignature() | No-op(실행 가능한 작업을 저장하지 않음). 엄격 모드에서 던집니다. | 디지털 서명에는 상용 NextPDF 에디션이 필요합니다. CertificateInfo 값 객체와 함께 모던 서명 API를 사용하십시오 — /integrations/tcpdf-compat/security-and-operations/ 참조. |
addEmptySignatureAppearance() | No-op. 엄격 모드에서 던집니다. | setSignature()와 동일한 상용 에디션 게이트입니다. |
endPage() | No-op. 엄격 모드에서 던집니다. | NextPDF는 페이지 라이프사이클을 자동으로 관리합니다. 호출을 제거하십시오. |
Open() | 안전한 no-op. 결코 던지지 않습니다. | NextPDF는 문서를 자동으로 엽니다. 호출을 제거해도 항상 안전합니다. |
이 어댑터를 통해서는 코어 엔진에서 서명을 사용할 수 없습니다. 어댑터는 엔진에 위임하는 모던 서명 진입점을 노출하지만, 기본 서명 지원은 상용 에디션으로 제한됩니다. 이 문서는 어떤 에디션에 대해서도 장기 검증(long-term-validation)이나 타임스탬프 서명 프로파일에 관해 주장하지 않습니다 — 정확하고 보수적인 설명은 /integrations/tcpdf-compat/security-and-operations/을 참조하십시오.
4. 해당 없음 메서드
섹션 제목: “4. 해당 없음 메서드”7개의 TCPDF 메서드는 PDF 출력에 영향을 주지 않으며 의도적으로 제외되었습니다. 이들을 호출해도 무해합니다.
| TCPDF 메서드 | 제외 이유 |
|---|---|
setDocCreationTimestamp() / setDocModificationTimestamp() | 상태는 어댑터에 보관되지만 문서 XMP 메타데이터와 연결되지 않습니다. 출력에 보이지 않습니다. |
setSRGBmode() | NextPDF 색상 관리는 이 플래그와 무관합니다. |
setPDFVersion() | NextPDF는 자신의 conformance/output 프로파일에서 PDF 버전을 선택하며, 직접적인 setter가 없습니다. 어댑터는 알림(notice)을 발행하고 계속 진행합니다. |
setDocInfoUnicode() | NextPDF는 항상 Unicode이므로, 이 플래그는 설계상 no-op입니다. |
setDefaultMonospacedFont() | 엔진에 해당하는 항목이 없으며, 대신 HTML/CSS 스타일링이 적용됩니다. |
setFontSubsetting() | NextPDF는 임베드된 폰트를 항상 서브셋팅하므로, 이 플래그는 사실상 항상 켜져 있습니다. |
PDF 버전은 엔진에 의해 고정됩니다. 출력은 PDF 2.0(ISO 32000-2)으로 작성됩니다. ISO 32000-2 §7.5.2은 준수 작성기(conforming writer)가 파일 헤더나 카탈로그 Version 항목에서 문서 버전을 2.0으로 식별한다고 명시합니다. 또한 저장 시 파일 버전이 이전 버전으로 낮춰지지 않는다고 명시합니다. 이는 어댑터 동작과 일치합니다: setPDFVersion('1.4') 같은 호출로는 이 어댑터를 통해 이전 PDF 버전을 대상으로 출력할 수 없습니다. 고정된 절(clause) 다이제스트는 페이지 프런트매터 citations에 있습니다.
5. 모던 API 드리프트 메서드
섹션 제목: “5. 모던 API 드리프트 메서드”TCPDF API와 모던 API를 혼합하는 코드가 계속 컴파일될 수 있도록, NextPDF 코어 v5.1+의 17개 메서드가 어댑터(트레이트 AdaptsDriftV51)에 노출됩니다. 이들은 TCPDF 6.x에 해당하는 항목이 없습니다. 예: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). 이들은 TCPDF 호환성 계약의 일부가 아니므로 모던 API로 취급하십시오.
6. 사용 중단 및 대체 지침
섹션 제목: “6. 사용 중단 및 대체 지침”| 코드가 다음을 호출한다면… | 상태 | 대신 이렇게 하십시오 |
|---|---|---|
Error() | 동작 변경(강화됨) | TCPDF의 die()는 던져지는 RuntimeException으로 대체됩니다. 위험한 호출은 try/catch로 감싸고, 프로세스 종료에 의존하지 마십시오. |
setPDFVersion() | 해당 없음 | 제거하십시오. 출력은 항상 PDF 2.0입니다. |
setUserRights() | PDF 2.0에서 사용 중단됨 | 제거하십시오. 이 호출은 E_USER_DEPRECATED 알림을 발행하며 무시됩니다. |
setSignature() | 코어에서 미구현 | 상용 에디션의 모던 서명 API로 마이그레이션하십시오. |
추가 매개변수가 있는 Image(...) | 무음 무시 | file, x, y, w, h로 줄이고, 클릭 가능한 이미지가 필요하면 Document::link()를 추가하십시오. |
endPage() / Open() | 미구현 / no-op | 제거하십시오. |
7. 안전한 마이그레이션 단계
섹션 제목: “7. 안전한 마이그레이션 단계”- 패키지를 설치한 뒤 코드 변경 없이 기존 스위트를 어댑터에 대해 실행하십시오 — /integrations/tcpdf-compat/install/ 및 /integrations/tcpdf-compat/quickstart/ 참조.
- 전용 감사 실행에서 엄격 모드를 활성화하십시오(프로덕션에서는 사용하지 마십시오):
$pdf->setStrictMode(true);. 모든TcpdfNotImplementedException을 수집하십시오. 각 예외는 무시된 정확한 매개변수와 마이그레이션 힌트를 명시합니다. - 예외가 던져지는 각 지점마다 다음 중 하나를 선택하십시오: 무시된 매개변수를 제거하거나,
$pdf->getDocument()를 통해 해당 호출을 모던 API로 마이그레이션하십시오. - 정확한 PDF 바이트를 단언하는 모든 테스트는 재기준화하고, 대신 렌더링된 콘텐츠나 구조적 속성을 단언하십시오.
- 엄격 모드를 끄고 감사가 끝난 코드 경로를 배포하십시오. 리팩터링 중 회귀를 잡을 수 있도록 주기적인 엄격 모드 CI 작업을 유지하십시오.
코드를 포함한 전체 절차는 /integrations/tcpdf-compat/migration/을 참조하십시오.
참고 항목
섹션 제목: “참고 항목”docs/TCPDF_COVERAGE.md— 권위 있고 테스트로 검증된 커버리지 매트릭스(저장소 내)- /integrations/tcpdf-compat/migration/ — 엔드투엔드 TCPDF→NextPDF 마이그레이션 전략
- /integrations/tcpdf-compat/configuration/ — 엄격 모드 및 어댑터 구성
- /integrations/tcpdf-compat/security-and-operations/ — 암호화 및 서명 태세
- /integrations/tcpdf-compat/integration/ — 어댑터를 애플리케이션에 연결하기
- /integrations/tcpdf-compat/boot-and-discovery/ — 클래스 별칭 등록 및 파사드 노출