NextPDF compat-legacy 통합

한눈에 보기

이 페이지에서는 nextpdf/compat-legacy를 애플리케이션에 연결해 기존 TCPDF 6.x 코드가 NextPDF 엔진에서 실행되도록 하는 방법을 설명합니다. 이 패키지는 마이그레이션 보조 도구이며, 영구적인 심이 아닙니다. 목표는 최신 API를 채택한 뒤 이를 제거하는 것입니다(/integrations/tcpdf-compat/migration/ 참조). 이 패키지는 TCPDF 호환 대안이며, 그대로 교체 가능한 클론은 아닙니다. 조사된 TCPDF 메서드 약 120개 중 94개가 직접 위임됩니다. 나머지는 문서화된 동작 차이를 동반합니다(/integrations/tcpdf-compat/method-coverage/ 참조).

설치

composer require nextpdf/compat-legacy:^3.0

이는 nextpdf/core ^3.0을 전이적으로 해결합니다. 전체 요구 사항과 검증 절차는 /integrations/tcpdf-compat/install/에서 확인할 수 있습니다.

부팅 및 자동 검색

오토로드 시점에 전역 연결은 수행되지 않습니다. 패키지를 require해도 전역 \TCPDF가 생성되지 않습니다. 호출 지점에서 클래스를 어떻게 해석할지는 사용자가 선택합니다:

권장(명시적 임포트). 각 파일의 use/require 줄을 use NextPDF\Compat\Tcpdf\TCPDF;로 변경합니다. 이 방식은 명확하며 grep으로 찾기 쉽습니다.
옵트인 전역 별칭. 부팅 시 LegacyBootstrap::enableAliases()를 한 번 호출하여 \TCPDF와 네 개의 헬퍼 클래스를 등록합니다. 단, 해당 이름이 아직 사용되고 있지 않은 경우에만 등록됩니다. 메커니즘, 멱등성, 실제 TCPDF와의 충돌 규칙은 /integrations/tcpdf-compat/boot-and-discovery/에서 설명합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

컨테이너 바인딩

이 패키지는 프레임워크 서비스 프로바이더나 번들을 제공하지 않습니다. 통합 계층은 사용자가 직접 소유하는 얇은 계층입니다. 문서마다 새 어댑터를 반환하는 팩토리를 바인딩해야 합니다. 공유 싱글톤은 절대 사용하지 않습니다. 문서 상태는 인스턴스별로 유지되기 때문입니다(/integrations/tcpdf-compat/production-usage/ § 동시성 참조).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

Symfony의 경우 팩토리를 비공유 서비스로 등록합니다. Laravel의 경우 bind로 바인딩합니다(singleton이 아님). 그래야 해결할 때마다 새 인스턴스가 생성됩니다. 패키지 자체는 프레임워크에 구애받지 않습니다.

구성 게시

게시할 수 있는 프레임워크 구성 파일은 없습니다. 레거시 K_* / PDF_* 상수(첫 인스턴스를 생성하기 전에 부트스트랩에서 정의)를 통해 구성하거나, 최신 불변 NextPDF\Compat\Tcpdf\Config\AdaptationConfig 객체로 구성할 수 있습니다. 자세한 내용은 /integrations/tcpdf-compat/configuration/에서 확인할 수 있습니다.

서비스 프로바이더 / 번들 스모크 테스트

연결 후에는 통합이 유효한 PDF를 생성하는지 확인합니다. 이는 tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php가 단언하는 표면을 그대로 반영합니다:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

HTTP 또는 워커 컨텍스트에서는 Output(..., 'F') 또는 'S'을 사용합니다. 인라인 경로에 의존하지 않습니다. 전체 운영 지침은 /integrations/tcpdf-compat/production-usage/에 있습니다.

공개 API 진입점

진입점	용도
`NextPDF\Compat\Tcpdf\TCPDF`	TCPDF 호환 파사드입니다. 문서마다 생성합니다.
`TCPDF::getDocument()`	래핑된 `NextPDF\Core\Document`을 반환하며, 최신 API로 넘어갈 수 있는 탈출구입니다.
`TCPDF::setStrictMode(bool)`	마이그레이션 감사 토글입니다(/integrations/tcpdf-compat/configuration/ 참조).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	옵트인 전역 클래스 별칭입니다.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	최신 불변 구성 객체입니다.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	공유 compat 계약입니다.

TCPDF API 커버리지

테스트로 검증된 권위 있는 커버리지 매트릭스는 리포지터리 내 파일 docs/TCPDF_COVERAGE.md입니다. 독자를 위한 요약은 /integrations/tcpdf-compat/method-coverage/에 있으며, 미러링, 무시(silent-ignore), 미구현, 해당 없음 메서드를 다룹니다. “그대로 교체(drop-in replacement)” 또는 “100% 호환”이라고 주장하지 않습니다. 정확히는 알려져 있고 테스트된 표면과 문서화된 동작 차이를 갖춘 TCPDF 호환 대안이라고 설명해야 합니다.

참고

docs/TCPDF_COVERAGE.md — 권위 있는 커버리지 출처(리포지터리 내)
/integrations/tcpdf-compat/boot-and-discovery/ — 파사드 노출 및 별칭 메커니즘
/integrations/tcpdf-compat/method-coverage/ — 메서드별 동작 및 간극
/integrations/tcpdf-compat/migration/ — 단계별 마이그레이션 전략
/integrations/tcpdf-compat/production-usage/ — 부하가 있는 환경에서 어댑터 실행
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — 출력 동작 오라클