TCPDF에서 마이그레이션

이 가이드는 레거시 TCPDF(tecnickcom/tcpdf)에서 TCPDF-Next로 기존 프로젝트를 마이그레이션하는 과정을 안내합니다. TCPDF-Next는 완전한 재작성이며 드롭인 대체품은 아니지만, 마이그레이션 과정은 체계적이고 잘 정의되어 있습니다.

주요 차이점

기능	TCPDF (레거시)	TCPDF-Next
PHP 버전	5.3+	8.5+
PDF 버전	PDF 1.7	PDF 2.0
아키텍처	단일 모놀리식 클래스 (~27,000줄)	17개 모듈식 네임스페이스, 142개 클래스
API 스타일	절차적, PascalCase 메서드	플루언트 빌더, camelCase 메서드
타입 안전성	타입 없음	`declare(strict_types=1)`, enum, readonly
정적 분석	없음	PHPStan 레벨 8, 에러 0개
암호화	RC4, AES-128, AES-256	AES-256만 (PDF 2.0 리비전 6)
서명	기본 PKCS#7	PAdES B-B부터 B-LTA
PDF/A	PDF/A-1b (부분)	PDF/A-4 (전체 ISO 19005-4)
교차 참조	레거시 xref 테이블	교차 참조 스트림
폰트 처리	독자적 바이너리 포맷	표준 TTF/OTF, 자동 서브셋팅
HTML 파싱	정규식 기반 (제한적)	DOM 기반 엔진 (향상된 CSS 지원)
종속성	없음	없음

API 매핑: 이전 메서드에서 새 메서드로

가장 눈에 띄는 변화는 API 표면입니다. TCPDF-Next는 camelCase, 명명된 파라미터, 값 객체, 플루언트 빌더를 사용합니다:

레거시 TCPDF	TCPDF-Next	비고
`new TCPDF()`	`Document::create()`	플루언트 빌더, 명명된 파라미터
`$pdf->Cell()`	`$pdf->cell()`	camelCase
`$pdf->MultiCell()`	`$pdf->multiCell()`	camelCase
`$pdf->SetFont()`	`$pdf->setFont()`	camelCase
`$pdf->SetDrawColor()`	`$pdf->setDrawColor()`	camelCase
`$pdf->Output('file.pdf', 'F')`	`$pdf->save('file.pdf')`	명시적 메서드
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Enum 기반

문서 생성

TCPDF (이전):

php

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);
$pdf->SetCreator('My App');
$pdf->SetAuthor('John Doe');
$pdf->SetTitle('Invoice #12345');
$pdf->SetKeywords('invoice, payment, monthly');
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->SetMargins(15, 15, 15);
$pdf->SetAutoPageBreak(true, 15);
$pdf->AddPage();

TCPDF-Next (이후):

php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;
use YeeeFang\TcpdfNext\Document\Margins;

$pdf = PdfDocument::create()
    ->setCreator('My App')
    ->setAuthor('John Doe')
    ->setTitle('Invoice #12345')
    ->setKeywords(['invoice', 'payment', 'monthly'])
    ->setPageFormat(PageFormat::A4)
    ->setOrientation(Orientation::PORTRAIT)
    ->setMargins(Margins::uniform(15))
    ->setAutoPageBreak(true, bottomMargin: 15)
    ->build();

$page = $pdf->addPage();

구성 변경: 상수에서 Enum으로

레거시 TCPDF는 정수 상수와 매직 문자열을 사용했습니다. TCPDF-Next는 PHP 8.1+ enum을 사용합니다:

php

// TCPDF: 암호화 모드를 위한 매직 정수
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3);

// TCPDF-Next: 타입 안전 enum
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256)
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY)
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->apply();

색상 처리: 배열에서 Color 값 객체로

php

// TCPDF: 단순 정수 배열
$pdf->SetDrawColor(255, 0, 0);
$pdf->SetFillColor(0, 128, 255);

// TCPDF-Next: Color 값 객체
use YeeeFang\TcpdfNext\Color\Color;

$canvas->setStrokeColor(Color::rgb(255, 0, 0));
$canvas->setFillColor(Color::rgb(0, 128, 255));
$canvas->setFillColor(Color::hex('#0080FF'));
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0));

페이지 크기: 문자열에서 PageSize 값 객체로

php

// TCPDF: 매직 문자열
$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage('L', 'LETTER');

// TCPDF-Next: 타입 안전 enum 및 값 객체
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->build();

$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE);
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

암호화: RC4/AES-128에서 AES-256만으로

TCPDF-Next는 모든 레거시 암호화 알고리즘을 제거합니다. 애플리케이션이 RC4 또는 AES-128 암호화를 사용하고 있다면 AES-256으로 반드시 업그레이드해야 합니다:

php

// TCPDF: 여러 알고리즘 (안전하지 않은 것 포함)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- 안전하지 않음
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- 안전하지 않음
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: AES-256만 (유일한 안전한 옵션)
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256) // 유일한 옵션
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY)
    ->apply();

WARNING

레거시 TCPDF로 RC4 또는 AES-128으로 암호화된 PDF는 AES-256으로 재암호화해야 합니다. RC4 암호화는 의미 있는 보안을 제공하지 않습니다 — 몇 초 만에 깨뜨릴 수 있는 도구가 존재합니다.

브레이킹 체인지 체크리스트

마이그레이션을 시작하기 전에 이 체크리스트를 검토하세요:

[ ] PHP 8.5+ 필수 — PHP 런타임을 업그레이드하세요. PHP 7.x 및 8.0-8.4는 지원되지 않습니다.
[ ] 네임스페이스 변경 — TCPDF 클래스 참조를 YeeeFang\TcpdfNext\... 네임스페이스로 교체합니다.
[ ] camelCase 메서드 — SetFont()은 setFont()으로, MultiCell()은 multiCell()로 변경 등.
[ ] 생성자 교체 — new TCPDF(...)은 PdfDocument::create()->...->build()로 변경.
[ ] 출력 메서드 교체 — Output('file.pdf', 'F')은 save('file.pdf')로 변경.
[ ] 폰트 포맷 변경 — TCPDF 바이너리 폰트 파일(.php + .z)을 원본 TTF/OTF 파일로 교체합니다.
[ ] 머리글/바닥글 메서드 — 클래스 상속(extends TCPDF)을 이벤트 콜백(onPageHeader())으로 교체합니다.
[ ] 암호화 업그레이드 — RC4 및 AES-128이 제거되었습니다. AES-256으로 마이그레이션합니다.
[ ] 색상 배열 — 단순 [255, 0, 0] 배열을 Color::rgb(255, 0, 0)으로 교체합니다.
[ ] 문자열 페이지 크기 — 'A4' 문자열을 PageFormat::A4 enum 값으로 교체합니다.
[ ] 키워드 포맷 — 쉼표로 구분된 문자열을 배열로 변경: 'a, b'를 ['a', 'b']로.
[ ] 단위 파라미터 제거 — TCPDF-Next는 기본적으로 밀리미터를 사용합니다(문서별 구성 가능).
[ ] 반환 타입 — 많은 메서드가 void 대신 타입이 있는 결과를 반환합니다. #[\NoDiscard] 반환값을 사용합니다.

호환성 레이어 (점진적 마이그레이션)

대규모 코드베이스를 위해 TCPDF-Next는 대부분의 레거시 메서드 호출을 매핑하는 호환성 레이어를 제공합니다:

php

// 임포트를 교체 — 기존 코드가 계속 작동합니다
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

호환성 레이어는 TCPDF의 퍼블릭 API의 약 80%를 커버합니다. 지원되지 않는 메서드는 현대적 대안에 대한 안내와 함께 DeprecatedMethodException을 발생시킵니다.

WARNING

호환성 레이어는 마이그레이션 보조 도구이지 영구적인 솔루션이 아닙니다. 오버헤드를 추가하며 TCPDF-Next의 고급 기능(PAdES 서명, PDF/A-4, 교차 참조 스트림)을 노출하지 않습니다. 네이티브 API로의 마이그레이션 완료를 계획하세요.

완전한 API 매핑

30개 이상의 메서드를 커버하는 포괄적인 메서드별 레퍼런스는 API 매핑 테이블을 참조하세요.

더 읽을거리

API 매핑 테이블 — 완전한 메서드별 매핑
보안 개요 — 마이그레이션에서 해결된 CVE 수정
API 레퍼런스 — 전체 TCPDF-Next API 문서
FAQ — 일반적인 마이그레이션 질문

TCPDF에서 마이그레이션 ​

주요 차이점 ​

API 매핑: 이전 메서드에서 새 메서드로 ​

문서 생성 ​

구성 변경: 상수에서 Enum으로 ​

색상 처리: 배열에서 Color 값 객체로 ​

페이지 크기: 문자열에서 PageSize 값 객체로 ​

암호화: RC4/AES-128에서 AES-256만으로 ​

브레이킹 체인지 체크리스트 ​

호환성 레이어 (점진적 마이그레이션) ​

완전한 API 매핑 ​

더 읽을거리 ​