TCPDF 호환성 API 참조

한눈에 보기

nextpdf/compat-legacy 패키지는 핵심 클래스인 NextPDF\Compat\Tcpdf\TCPDF를 노출합니다. 이 클래스는 TCPDF 6.x 공개 API를 그대로 따르면서 렌더링은 최신 NextPDF 엔진에서 수행합니다. 또한 몇 가지 보조 구성 요소도 노출합니다. 전역 클래스 별칭을 위한 LegacyBootstrap, AdaptationConfig/LegacyDefaults 구성 표면, 내부 브리지 클래스(출력, 생성자, 색상, 단위, 페이지 형식), 호환성 예외가 포함됩니다. 이는 영구 종속성이 아니라 마이그레이션 보조 도구입니다. 레거시 메서드의 전체 상태는 메서드 커버리지 표에서 확인할 수 있습니다. 이 페이지에서는 애플리케이션 코드가 의도적으로 의존해야 하는 표면을 문서화합니다.

여기서 시작합니다: 이 패키지를 처음 사용한다면 NextPDF\Compat\Tcpdf\TCPDF를 생성하고, 평소처럼 TCPDF 호출(AddPage(), SetFont(), Cell())을 수행한 뒤 Output($name, $dest)로 마무리합니다. 이 클래스 하나가 아래에 나오는 거의 모든 기능의 진입점입니다. 실행 가능한 시작점은 일반 작업에서 확인할 수 있습니다.

일반 작업

다음은 이 패키지에서 가장 자주 수행하는 실제 작업입니다. 각 블록은 어댑터 기준으로 소스 검증을 마쳤으며 그대로 실행할 수 있습니다.

익숙한 TCPDF 호출로 PDF를 생성하고 이를 문자열로 캡처합니다(큐, HTTP 응답 또는 스토리지용):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

동작 방식: TCPDF 형태의 어댑터를 통해 PDF 2.0 문서를 만들고 원시 바이트(%PDF...)를 반환합니다. 대상 'S'는 OutputBridge를 거쳐 Document::getPdfData()로 라우팅되므로 출력 스트림으로 내보내지 않습니다. 워커나 컨트롤러 내부에서도 안전합니다.

부팅 시 전역 별칭을 한 번 등록하면 기존 new \TCPDF(...) 코드를 소스 수정 없이 실행할 수 있습니다:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

동작 방식: enableAliases()는 해당 이름이 아직 정의되지 않은 경우에만 \TCPDF(및 \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES 헬퍼)를 멱등적으로 등록하므로, 수정하지 않은 레거시 코드가 어댑터에서 실행됩니다.

누락된 모든 TCPDF 매개변수를 자동으로 드러내 마이그레이션 감사를 수행합니다:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

동작 방식: setStrictMode(true)를 설정하면 TCPDF 동작을 재현할 수 없는 호출은 무시된 매개변수를 명시하는 TcpdfNotImplementedException을 throw합니다. 이는 드러나지 않는 성능 저하를 마이그레이션 작업 목록으로 전환합니다(이 코드는 감사 단계에서만 실행해야 하며, 프로덕션에서는 절대 실행하지 않습니다).

주요 어댑터

이 표는 표준 어댑터 API 표면을 정리합니다. 생성할 클래스(TCPDF), 엄격 모드 및 이스케이프 해치 메서드, 구현 계약이 필요할 때 참조합니다.

기호	매개변수	기본 동작	반환값	throw 또는 실패 조건	참고
NextPDF\Compat\Tcpdf\TCPDF	생성자 매개변수는 ConstructorBridge를 통해 레거시 TCPDF 형태를 따릅니다.	NextPDF 문서를 기반으로 하는 어댑터를 생성합니다.	TCPDF	생성자 유효성 검사 또는 지원되지 않는 기능 예외입니다.	마이그레이션 중에 사용하고, 새로운 네이티브 NextPDF 코드에는 사용하지 않습니다.
TCPDF::getDocument()	없음.	기반 NextPDF 문서를 반환합니다.	NextPDF\Core\Document	예상되지 않음.	레거시 호출과 네이티브 호출을 혼용해야 하는 마이그레이션 코드를 위한 이스케이프 해치입니다.
TCPDF::getUnitConverter()	없음.	레거시 단위에서 생성된 변환기를 반환합니다.	UnitConverter	예상되지 않음.	마이그레이션 진단에 사용하고, 일반 애플리케이션 코드에는 사용하지 않습니다.
TCPDF::setStrictMode(bool $enabled)	엄격 모드 플래그입니다.	지원되지 않는 호환성 동작에 대한 명시적 실패를 활성화하거나 비활성화합니다.	static	예상되지 않음.	마이그레이션 감사 중에는 활성화 상태로 유지하세요.
TCPDF::isStrictMode()	없음.	현재 엄격 모드 플래그를 반환합니다.	bool	예상되지 않음.	테스트 단언에 유용합니다.
TCPDF 레거시 메서드	메서드에 따라 다름.	지원되는 메서드는 코어 문서 호출에 매핑되며, 지원되지 않는 메서드는 명시적으로 실패합니다.	메서드에 따라 다름.	TcpdfNotImplementedException 또는 UnsupportedFeatureException.	메서드에 의존하기 전에 메서드 커버리지를 확인합니다.
CompatAdapterInterface::getDocument()	없음.	TCPDF가 구현하는 계약 메서드입니다.	Document	예상되지 않음.	도구가 네이티브 문서에 접근할 수 있도록 합니다.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	파일 이름과 레거시 대상입니다.	출력 브리지에 위임합니다.	string	코어 쓰기 또는 지원되지 않는 대상 오류입니다.	레거시 TCPDF 출력 진입점을 그대로 따릅니다. 구체 구현인 TCPDF::Output가 'doc.pdf'/'I' 기본값을 제공합니다.

레거시 메서드 그룹

이 표는 어댑터가 다루는 TCPDF 메서드 계열을 보여 줍니다. 메서드 커버리지에서 정확한 상태를 확인하기 전에 특정 레거시 호출이 대략 어디에 해당하는지 파악할 때 참조합니다.

그룹	대표 기호	기본 동작	참고
수명 주기 및 출력	Open(), Close(), Output(), getPDFData()	네이티브 문서 위에서 TCPDF 형태의 문서 수명 주기를 유지합니다.	마이그레이션 후에는 네이티브 출력 API를 사용합니다.
메타데이터	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	메타데이터 설정자를 기반 문서에 매핑합니다.	메타데이터 정규화는 애플리케이션 코드에서 유지하세요.
페이지 및 위치 지정	AddPage(), setPage(), lastPage(), GetX(), SetXY()	레거시 단위와 좌표를 네이티브 페이지 작업으로 변환합니다.	마이그레이션 후 절대 위치 지정을 시각적으로 확인해야 합니다.
여백 및 레이아웃	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	호환성 상태를 저장하고 지원되는 값을 매핑합니다.	복잡한 TCPDF 페이지 나누기 동작은 수동 검토가 필요할 수 있습니다.
글꼴 및 텍스트	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	일반적인 텍스트 작업을 네이티브 글꼴 및 텍스트 API로 라우팅합니다.	프로덕션 글꼴로 CJK 및 인코딩 동작을 확인해야 합니다.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	지원되는 HTML을 네이티브 HTML 파이프라인으로 보냅니다.	네이티브 렌더러는 완전한 TCPDF HTML 복제본이 아닙니다.
이미지 및 그리기	Image(), Line(), Rect(), Circle(), SetDrawColor()	지원되는 그래픽 작업을 어댑터 계층을 통해 매핑합니다.	지원되지 않는 벡터 또는 특수 형식은 명시적으로 실패합니다.
내비게이션 및 주석	Bookmark(), AddLink(), SetLink(), Annotation()	매핑된 경우 일반적인 내비게이션 호출을 보존합니다.	생성된 개요와 링크를 검증해야 합니다.
보안 및 서명	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	지원되는 레거시 보안 호출을 네이티브 기능에 연결합니다.	암호화 출력은 별도의 검증 게이트로 취급해야 합니다.
폼, 템플릿, 변환	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	지원되는 하위 집합을 구현하고, 지원되지 않는 동작에 대해서는 명시적으로 실패합니다.	롤아웃 전에 각 호출을 메서드 커버리지와 대조하여 감사해야 합니다.

부트스트랩 및 구성

어댑터를 애플리케이션 부팅 경로에 연결할 때, 즉 전역 별칭을 등록하고 레거시 상수와 최신 AdaptationConfig 중에서 선택할 때 이 표를 참조합니다.

기호	매개변수	기본 동작	반환값	throw 또는 실패 조건	참고
LegacyBootstrap::enableAliases()	없음.	호환성 별칭을 한 번 등록합니다.	void	자동 로드 또는 환경 오류입니다.	레거시 코드가 TCPDF 이름이 전역에 존재할 것으로 기대하는 경우에만 사용합니다.
LegacyBootstrap::isRegistered()	없음.	별칭이 등록되었는지 여부를 보고합니다.	bool	예상되지 않음.	부트스트랩 테스트에 유용합니다.
LegacyBootstrap::resetForTesting()	없음.	테스트를 위해 등록 상태를 지웁니다.	void	예상되지 않음.	테스트 전용 헬퍼입니다.
AdaptationConfig	어댑터 플래그 및 마이그레이션 제어입니다.	생략하면 패키지 기본값을 사용합니다.	AdaptationConfig	잘못된 옵션 값입니다.	마이그레이션 감사 중에는 구성을 명시적으로 유지합니다.
AdaptationConfig::fromLegacyConstants()	없음.	알려진 레거시 상수를 읽어 구성을 빌드합니다.	AdaptationConfig	잘못된 레거시 상수 값입니다.	대규모 레거시 애플리케이션을 위한 전환용 헬퍼입니다.
LegacyDefaults	없음.	기본 레거시 값을 제공합니다.	기본값 집합.	예상되지 않음.	호환성 기본값을 위한 중심 위치입니다.

브리지 및 헬퍼

다음은 어댑터가 사용하는 내부 변환 클래스입니다. 이 표는 주로 어댑터 커버리지에 기여하거나 레거시 인수가 어떻게 변환되었는지 진단할 때 참조하며, 일반 애플리케이션 코드용은 아닙니다.

기호	매개변수	기본 동작	반환값	throw 또는 실패 조건	참고
ConstructorBridge	레거시 생성자 인수 목록입니다.	레거시 옵션을 NextPDF 구성으로 정규화합니다.	생성자 데이터입니다.	잘못된 레거시 인수 값입니다.	어댑터가 내부적으로 사용합니다.
CellParameterAdapter	TCPDF 셀 매개변수입니다.	레거시 위치 인수를 코어 텍스트 레이아웃 옵션에 매핑합니다.	조정된 매개변수입니다.	잘못된 치수 또는 정렬입니다.	새 코드에서는 네이티브 코어 메서드를 사용합니다.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	네이티브 문서, 파일 이름, 레거시 대상입니다.	inline/download/저장 동작을 NextPDF 출력 API에 매핑합니다.	string	코어 쓰기 오류, 지원되지 않는 대상입니다.	출력하기 전에 파일 이름과 스토리지 루트를 검증해야 합니다.
OutputBridge::resolveDestination(string $dest)	레거시 대상 코드입니다.	대상을 네이티브 출력 대상으로 변환합니다.	OutputDestination	지원되지 않는 대상 오류입니다.	대상 매핑을 중앙 집중화합니다.
ColorTranslator	TCPDF 색상 인수입니다.	레거시 색상 형식을 정규화합니다.	코어 색상 값.	잘못된 색상 값입니다.	색상 및 그리기 관심사에서 사용합니다.
PageFormatResolver	레거시 페이지 형식 입력입니다.	알려진 이름을 코어 페이지 크기에 매핑합니다.	페이지 형식 값.	알 수 없는 형식입니다.	마이그레이션 후에는 명시적인 네이티브 페이지 크기를 사용합니다.
UnitConverter	레거시 측정값 및 단위입니다.	코어 단위로 변환합니다.	숫자 값.	잘못된 단위입니다.	레거시 레이아웃 동작을 보존하는 데 도움이 됩니다.

예외

마이그레이션 호출이 명시적으로 실패할 때 이 표를 사용합니다. 어떤 예외가 “구현되지 않음”을 의미하고 어떤 예외가 “알려졌지만 지원되지 않음”을 의미하는지, 그리고 각각에서 어떻게 복구하는지 설명합니다.

기호	의미	복구
TcpdfNotImplementedException	어댑터가 요청된 레거시 메서드를 의도적으로 구현하지 않습니다.	호출을 네이티브 NextPDF API로 교체하거나 종속성을 제거합니다.
TcpdfNotImplementedException::forSilentIgnore()	레거시 호출이 이전에는 무시되었겠지만, 마이그레이션 명확성을 위해 드러납니다.	명시적인 no-op 동작이 허용되는지 결정합니다.
TcpdfNotImplementedException::forUnimplemented()	레거시 호출에 구현된 어댑터 경로가 없습니다.	호출을 교체하거나 마이그레이션 코드 뒤에 격리합니다.
UnsupportedFeatureException	레거시 기능은 알려져 있지만 어댑터 경계 내에서 지원되지 않습니다.	마이그레이션 지침을 확인하고 해당 기능을 애플리케이션 어댑터 뒤에 격리합니다.
UnsupportedFeatureException::forMethod()	메서드별 지원되지 않는 기능 오류를 생성합니다.	일관된 실패 메시지를 보존하기 위해 호환성 기여에서 사용합니다.

개발 참고 사항

• 어댑터는 마이그레이션 도구로 취급합니다. 새 코드는 코어 NextPDF API를 직접 대상으로 삼아야 합니다.
• 지원되지 않는 동작은 명시적으로 실패해야 합니다. 애플리케이션이 그 위험을 명시적으로 수용하지 않는 한, 호환성 예외를 catch하여 부분 문서로 계속 진행해서는 안 됩니다.
• 마이그레이션 변경은 작게 유지하고 각 레거시 메서드를 커버리지 표와 대조하여 검증합니다.