NextPDF compat-legacy 부팅과 탐색

한눈에 보기

nextpdf/compat-legacy는 TCPDF 호환 파사드, 즉 NextPDF\Compat\Tcpdf\TCPDF 클래스를 노출하며, 이 클래스는 NextPDF 엔진에 위임합니다. 이는 호환성 계층이며 드롭인 복제본이 아닙니다. 조사된 약 120개의 TCPDF 6.x 메서드 중 94개를 직접 위임으로 다룹니다. 나머지 메서드에는 문서화된 동작상의 차이가 있습니다(/integrations/tcpdf-compat/method-coverage/ 참고).

오토로드 시점의 전역 와이어링은 없습니다. 기본적으로 패키지를 require 한다고 해서 전역 \TCPDF 클래스가 생성되지는 않습니다. 전역 별칭은 명시적으로 옵트인해야 하며, 마이그레이션 중에는 권장 방식에 따라 파일별로 어댑터 클래스를 import 합니다.

TCPDF 파사드가 노출되는 방식

파사드는 일반적인 PSR-4 오토로드 클래스입니다.

항목	값
파사드 클래스	`NextPDF\Compat\Tcpdf\TCPDF`
PSR-4 접두사	`NextPDF\Compat\Tcpdf\`가 `src/Compat/Tcpdf/`에 매핑됩니다
공유 컨트랙트	`NextPDF\Compat\Contracts\CompatAdapterInterface`
탈출구	`TCPDF::getDocument()`는 래핑된 `NextPDF\Core\Document`를 반환합니다

이 클래스는 의도적으로 final이 아닙니다. 레거시 TCPDF 사용자는 흔히 TCPDF를 서브클래싱하여 Header()와 Footer()를 오버라이드하므로, 어댑터는 이 확장 지점을 보존합니다. 내부적으로 이 클래스는 파사드입니다. 이 클래스는 단일 책임 관심사별 트레이트 25개를 조합하며, 모든 PDF 작업을 빌드 시점에 생성되는 Document 인스턴스에 위임합니다.

부팅 시퀀스

Diagram

생성 과정이 유일한 “부팅” 단계입니다. 패키지 자체에는 서비스 컨테이너 등록도, 프레임워크 부트스트래핑도 없습니다. 프레임워크 통합은 직접 추가하는 얇은 계층입니다. /integrations/tcpdf-compat/integration/ 를 참고하세요.

LegacyDefaults::register()는 멱등합니다. 해당 상수가 아직 정의되어 있지 않은 경우에만 상수를 정의합니다. 애플리케이션에서 정의한 상수는 첫 생성 전에 정의되어 있기만 하면 항상 우선합니다(/integrations/tcpdf-compat/configuration/ § Configuration resolution order 참고).

옵트인 전역 클래스 별칭

코드베이스가 전역 네임스페이스에서 new \TCPDF(...)를 호출하고 아직 그 호출 지점을 변경할 수 없다면, 애플리케이션 부팅 시 전역 별칭을 한 번 등록하세요.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases()는 \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS, 그리고 \TCPDF_IMAGES를 등록합니다. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php로 검증되는 동작은 다음과 같습니다.

멱등합니다 — 두 번 호출해도 예외를 던지지 않으며 한 번만 등록합니다.
LegacyBootstrap::isRegistered()는 실행되었는지 여부를 보고합니다.
등록 이후의 new \TCPDF()는 어댑터의 인스턴스입니다.

실제 TCPDF 설치본과의 충돌 회피

이 페이지에서 가장 중요한 규칙은 하나입니다.

enableAliases()는 해당 이름의 클래스가 아직 존재하지 않는 경우에만 별칭을 등록합니다(class_exists($alias, autoload: false)). 따라서:

tecnickcom/tcpdf가 설치되어 있고 그 \TCPDF가 먼저 로드되면, 별칭은 조용히 건너뛰어지고 코드는 어댑터가 아니라 레거시 TCPDF를 계속 사용합니다.
전역 별칭을 활성화한 채 두 라이브러리를 같은 프로세스에서 실행하는 것은 지원되지 않으며 모호한 동작을 야기합니다.

마이그레이션 중에는 파일별 명시적 import(use NextPDF\Compat\Tcpdf\TCPDF;)를 선호하세요. grep으로 찾기 쉽고 모호하지 않습니다. strict-mode 감사를 통과한 뒤에는 tecnickcom/tcpdf를 제거하세요(/integrations/tcpdf-compat/migration/ Stage 5 참고). \TCPDF가 잘못된 클래스로 해석되는 경우, /integrations/tcpdf-compat/troubleshooting/ 에 진단 방법이 있습니다.

컨테이너 바인딩

패키지에는 프레임워크 컨테이너 바인딩이 포함되어 있지 않습니다. 파사드를 컨테이너에 바인딩한다면, 문서마다 새 NextPDF\Compat\Tcpdf\TCPDF를 반환하는 팩토리를 바인딩하세요. Document 상태는 인스턴스별이며 서로 관련 없는 문서 간에 공유해서는 안 됩니다(/integrations/tcpdf-compat/production-usage/ § Concurrency 참고). 일반적인 바인딩 예시는 /integrations/tcpdf-compat/integration/ 에 나와 있습니다.

구성 해석 순서

생성 시 어댑터는 구성을 다음 순서로 해석합니다. 먼저 생성자 인수, 다음으로 애플리케이션에서 미리 정의한 기존 레거시 상수, 마지막으로 아직 정의되지 않은 모든 상수에 대한 LegacyDefaults의 TCPDF 6.2.13 기본값입니다. 전체 세부 내용과 최신 AdaptationConfig 객체에 대해서는 /integrations/tcpdf-compat/configuration/ 를 참고하세요.

진단

파사드가 와이어링되었고 엔진 링크가 해석되는지 확인하려면, 어댑터를 생성해 한 페이지짜리 PDF를 만든 다음 %PDF 접두사를 확인하세요. 이는 패키지 출력 테스트가 검증하는 것과 동일한 표면입니다. 실행 가능한 점검은 /integrations/tcpdf-compat/install/ § Verify the installation 에 있습니다.

별칭을 활성화하기 전에 실제 TCPDF 충돌을 감지하려면, enableAliases()를 호출할 시점에 전역 \TCPDF가 이미 존재하는지 확인하세요. 이미 존재한다면 별칭이 건너뛰어지므로, 어댑터에 의존하기 전에 충돌을 해결하세요(명시적 import를 사용하거나 실제 TCPDF를 제거).

TCPDF API 커버리지

권위 있고 테스트로 검증된 커버리지 매트릭스는 저장소의 docs/TCPDF_COVERAGE.md 파일입니다. 조용히 무시되는 메서드와 미구현 메서드 목록을 포함한 독자용 요약은 /integrations/tcpdf-compat/method-coverage/ 입니다. 이 패키지는 “드롭인 대체재”나 “100% TCPDF 호환”이라고 주장하지 않습니다. 알려져 있고 테스트된 호환성 표면과 문서화된 동작상의 차이를 갖춘 TCPDF 호환 대안입니다.

참고 자료

docs/TCPDF_COVERAGE.md — 권위 있는 커버리지 출처(저장소 내)
/integrations/tcpdf-compat/integration/ — 파사드를 application/framework에 와이어링하기
/integrations/tcpdf-compat/method-coverage/ — 메서드별 동작과 공백
/integrations/tcpdf-compat/migration/ — 단계적 마이그레이션 전략
/integrations/tcpdf-compat/troubleshooting/ — alias/real-TCPDF 충돌 진단
tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — 별칭 동작 오라클