NextPDF compat-legacy 개요

한눈에 보기

nextpdf/compat-legacy는 TCPDF 호환 대안입니다. NextPDF PDF 2.0 엔진 위에서 TCPDF 6.x 공개 API를 노출하는 호환 레이어입니다. 이 레이어의 역할은 단 하나입니다. 이미 TCPDF 6.x에 의존하는 코드베이스를 다시 작성하지 않고도 NextPDF 엔진에서 실행할 수 있게 하여, 마이그레이션을 한꺼번에 진행하는 대신 파일 단위로 진행할 수 있도록 돕습니다.

이 패키지는 TCPDF의 포크가 아니며, 동작을 보장하는 복제본으로 제시되지도 않습니다. TCPDF의 호출 시그니처를 유지하는 독립 구현입니다. 더 정확히는 조사된 약 120개의 TCPDF 6.x 메서드 중 94개를 직접 위임으로 처리하며, 나머지 메서드에는 문서화된 동작 차이가 있습니다 (/integrations/tcpdf-compat/method-coverage/ 참조).

무엇인가

마이그레이션 보조 도구. 이 패키지는 NextPDF compat 제품군의 일부입니다. 목적은 레거시 PDF 라이브러리에서 벗어나는 경로를 단축하는 것이지, 영구적인 의존성이 되는 것이 아닙니다. 최신 API를 채택해 나가면서 제거해 갈 발판으로 취급하십시오.
API 표면 어댑터. TCPDF 클래스 이름, 메서드 이름, 매개변수 순서 및 6.2.13 기본값을 제공합니다. 호출은 NextPDF\Core\Document 인스턴스로 위임됩니다.
독립적인 클린룸 구현. TCPDF 소스 코드, 빌드 아티팩트, 폰트 데이터 또는 기타 저작권 보호 대상 표현물은 이 패키지에 복사되거나 옮겨지지 않았습니다. TCPDF라는 이름은 상호 운용성 식별 목적으로만 사용됩니다. 공식 명시문은 패키지의 NOTICE 파일에 있습니다.

무엇이 아닌가

바이트 단위로 동일한 출력을 내는 “드롭인 대체품”이 아닙니다. 위임된 메서드는 눈에 보이는 결과가 호환되지만, 그 아래 엔진이 서로 다른 독립 PDF 2.0 구현이므로 렌더링된 PDF 바이트는 달라집니다.
“100% TCPDF 호환”도 아닙니다. 정의된 일부 메서드는 엔진이 사용하지 않는 레거시 매개변수를 받아들이거나 아무 동작도 하지 않습니다. 이러한 항목은 열거되어 있으며 테스트도 되어 있습니다. /integrations/tcpdf-compat/method-coverage/ 참조.
그 자체로 서명 또는 아카이브 제품도 아닙니다. 디지털 서명과 PDF/A 아카이브 적합성은 상용 NextPDF 에디션에서만 제공됩니다. 이 문서는 인증되었거나, 보증되었거나, 법적으로 유효한 서명에 대해 어떠한 주장도 하지 않습니다.

호환 레이어를 거쳐 마이그레이션하는 이유

대규모 애플리케이션 전반의 모든 TCPDF 호출을 한꺼번에 다시 작성하는 일은 위험도가 높고 점진적으로 출시하기도 어렵습니다. 호환 레이어를 사용하면 다음을 수행할 수 있습니다.

의존성을 교체하고 기존 테스트 스위트를 실행하여 어떤 부분이 변경 없이 이미 동작하는지 찾아냅니다.
엄격 모드를 감사 도구로 활용하여 TCPDF 동작을 정확히 재현할 수 없는 모든 지점을 열거합니다.
애플리케이션을 항상 출시 가능한 상태로 유지하면서 해당 호출 지점을 최신 NextPDF API로 하나씩 마이그레이션합니다.

최종 상태는 호환 레이어를 제거한 최신 NextPDF\Core\Document API입니다. 전체 전략은 /integrations/tcpdf-compat/migration/를 참조하십시오.

NextPDF 엔진에서 얻는 이점

TCPDF 호출이 위임되면 AES-256 표준 핸들러 암호화를 사용할 수 있고, 어댑터 전반에 PHPStan Level 10 타입 안전성이 적용된 PDF 2.0(ISO 32000-2) 엔진에서 실행됩니다. 출력은 항상 PDF 2.0으로 작성되며, 어댑터는 이전 PDF 버전을 하향 타깃으로 지정할 수 없습니다 (/integrations/tcpdf-compat/method-coverage/ §4 참조).

어댑터는 기존 TCPDF 6.2.13의 여러 함정에 대해 더 안전한 동작을 적용합니다.

레거시 동작	어댑터 동작
`Error()`가 `die()`를 호출하여 프로세스를 조용히 종료합니다	`Error()`가 `RuntimeException`을 throw합니다 — 관찰 및 포착 가능
마크업에서 PHP를 실행할 수 있었던 HTML 메서드	해당 우회 경로는 비활성화되어 있습니다 — 마크업이 PHP 실행을 유발할 수 없습니다
`Output()`가 직접 출력하여 워커 출력 버퍼를 손상시킬 수 있습니다	안전한 대상 브리지를 통해 출력이 라우팅됩니다
보호되지 않은 header/footer 재귀	재귀 보호가 적용됩니다

범위와 에디션

호환 레이어는 core 배포판에 포함되어 제공됩니다(nextpdf/compat-legacy, nextpdf/core ^3.0 필요). 표준 핸들러를 통한 암호화는 core에서 사용할 수 있습니다. 디지털 서명과 PDF/A 아카이브 적합성에는 상용 NextPDF 에디션이 필요합니다. 어댑터는 진입점을 노출하지만 core 경로는 서명 제품이 아닙니다. 정확한 명시 내용은 /integrations/tcpdf-compat/security-and-operations/를 참조하십시오.

다음으로 볼 곳

/integrations/tcpdf-compat/install/ — 패키지를 설치하고 엔진 연결을 확인합니다.
/integrations/tcpdf-compat/quickstart/ — 실행 가능하며 테스트로 검증되는 첫 번째 문서.
/integrations/tcpdf-compat/method-coverage/ — 각 TCPDF 메서드가 여기에서 정확히 무엇을 하는지.
/integrations/tcpdf-compat/migration/ — 파일 단위 마이그레이션 전략.
/integrations/tcpdf-compat/configuration/ — 엄격 모드 및 어댑터 구성.
/integrations/tcpdf-compat/production-usage/ — 부하가 걸린 상태와 워커에서 어댑터 실행하기.
/integrations/tcpdf-compat/security-and-operations/ — 암호화, 서명 태세, 강화.
/integrations/tcpdf-compat/troubleshooting/ — 일반적인 마이그레이션 실패와 그 해결 방법.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — 애플리케이션에 파사드를 연결하고 전역 클래스 별칭을 등록하기.

함께 보기

docs/TCPDF_COVERAGE.md — 공식 커버리지 매트릭스(저장소 내)
패키지 NOTICE — 독립 구현 고지문