compat-legacy 빠른 시작

한눈에 보기

이 페이지는 설치된 패키지로 완성된 PDF를 만들고, 마이그레이션 전에 엄격 모드 감사를 실행하는 과정까지 안내합니다. 모든 코드 블록은 패키지 테스트 스위트에서 검증하는 동작을 반영하므로, 여기에 표시된 출력은 테스트가 확인한 내용입니다.

시작하기 전에

패키지를 설치하고 엔진 연결을 확인합니다. /integrations/tcpdf-compat/install/를 따르세요. PHP 8.4가 필요하며, nextpdf/core ^3.0이 해결되어야 합니다.

1. 첫 문서 생성

import만 변경하고, TCPDF 스타일 호출은 그대로 유지합니다. 이것이 바로 tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php에서 검증하는 정확한 호출 표면입니다.

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

다음과 같이 실행합니다:

php examples/quickstart-first.php

quickstart.pdf 파일은 유효한 PDF 2.0입니다. 테스트 스위트는 동일한 문자열 출력이 S, F, E 대상과 getPDFData()에서 %PDF로 시작한다고 검증합니다.

출력 대상

Output($name, $dest)는 TCPDF 대상 코드를 안전한 출력 브리지를 통해 매핑합니다. 테스트 스위트에서 실행하는 동작은 다음과 같습니다:

$dest	동작	반환값
'S'	PDF를 문자열로 반환	PDF 바이트 (%PDF…)
'F'	지정된 경로에 PDF 쓰기	빈 문자열
'E'	base64 MIME 본문 반환	Content-Type: application/pdf 블록
'I'	인라인(기본값)	출력 브리지에 따름
'D'	다운로드	출력 브리지에 따름

레거시 TCPDF와 달리, Output()는 활성 출력 버퍼로 직접 출력하지 않으므로, 자체 응답을 제어하는 큐 워커나 HTTP 핸들러 내부에서 안전하게 호출할 수 있습니다. /integrations/tcpdf-compat/production-usage/를 참조하세요.

2. 기존 TCPDF 코드를 변경 없이 실행

실제 마이그레이션에서는 먼저 import나 별칭만 변경한 채 기존 코드를 실행합니다. 코드베이스가 전역 네임스페이스의 new \TCPDF(...)를 호출한다면, 부팅 시 opt-in 별칭을 한 번 활성화하세요 (/integrations/tcpdf-compat/boot-and-discovery/에서 다룹니다):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases()는 멱등적입니다. 즉, 해당 클래스가 아직 존재하지 않는 경우에만 \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS, \TCPDF_IMAGES를 등록합니다. 패키지 테스트 tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php는 별칭 등록, 호출의 멱등성, new \TCPDF()가 어댑터의 인스턴스임을 검증합니다. 동일한 프로세스에 실제 TCPDF 라이브러리가 로드되어 있다면 별칭을 활성화하지 마세요 — /integrations/tcpdf-compat/troubleshooting/를 참조하세요.

3. 엄격 모드로 감사

이 단계는 마이그레이션을 안전하게 만듭니다. 엄격 모드가 꺼져 있으면(기본값), TCPDF 동작을 재현할 수 없는 메서드는 별도 알림 없이 저하됩니다. 엄격 모드가 켜져 있으면, 무시된 매개변수를 정확히 알려 주며 TcpdfNotImplementedException을 던집니다. 전용 감사 패스에서만 실행하고, 프로덕션에서는 절대 실행하지 마세요.

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

패키지 테스트 tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php는 이 정확한 호출이 엄격 모드에서는 예외를 던지고 기본 모드에서는 별도 알림 없이 계속되며, 메시지에 메서드 이름과 무시된 매개변수가 포함됨을 검증합니다. 수집된 예외를 마이그레이션 작업 목록으로 사용하세요 — /integrations/tcpdf-compat/migration/를 참조하세요.

4. 필요할 때 최신 API에 접근

모든 어댑터 인스턴스는 기반 엔진의 문서 객체를 노출합니다. 이를 사용하여 TCPDF에 대응되는 항목이 없는 최신 NextPDF 메서드를 호출하세요:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument()는 어댑터가 감싸는 NextPDF\Core\Document를 반환합니다. 이것이 권장되는 전환 경로입니다: 어댑터를 제거할 수 있을 때까지 호출 지점을 하나씩 최신 API로 마이그레이션하세요.

즉시 예상해야 할 동작 차이

• MultiCell()는 렌더링된 셀 개수가 아니라 1을 반환합니다. MultiCell()의 반환값으로 분기하는 코드는 조정이 필요합니다.
• Error()는 die()를 호출하는 대신 RuntimeException을 던집니다. 프로세스 종료에 의존하던 코드는 예외를 잡아야 합니다.
• 정확한 PDF 바이트는 TCPDF 출력과 다릅니다. 바이트 수준 테스트 단언은 다시 기준화하고, 대신 렌더링된 콘텐츠를 단언하도록 조정하세요.

메서드별 전체 목록은 /integrations/tcpdf-compat/method-coverage/.에 있습니다.

다음 단계

• /integrations/tcpdf-compat/migration/ — 파일별 전체 마이그레이션 전략.
• /integrations/tcpdf-compat/configuration/ — 엄격 모드, 기본값, 최신 구성 객체.
• /integrations/tcpdf-compat/production-usage/ — 워커, 출력 버퍼, 그리고 성능.
• /integrations/tcpdf-compat/security-and-operations/ — 암호화 및 서명 태세.

참고

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — 출력 동작 오라클
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — 엄격 모드 오라클
• docs/TCPDF_COVERAGE.md — 권위 있는 커버리지 매트릭스