레거시에서 벗어나기: TCPDF, FPDF, 그리고 그 동료들

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

한눈에 보기

여러분의 PDF가 TCPDF, FPDF, mPDF, 또는 dompdf로 생성된다면, 그 코드는 아마 여전히 작동할 것입니다. 바로 그 점 때문에 문제를 알아차리기가 쉽지 않습니다. 라이브러리는 돌아가고, 파일은 열리며, 그 간극은 누군가 서명되고, 보관 가능하며, 접근성을 갖춘 문서를 요구하는데 그 답이 “여기서는 할 수 없습니다”가 되는 날에야 비로소 드러납니다.

이 페이지는 마이그레이션 이야기입니다. 그 벽이 무엇인지, 그것이 우연한 것이 아니라 왜 구조적인지, 그리고 NextPDF가 어떻게 그 벽에서 벗어나는 단계적 경로를 제공하는지 — 바이트 단위로 동일하게 끼워 넣는다는 약속이 아니라 마이그레이션 보조 도구인 TCPDF 호환 표면을 포함하여 — 설명합니다.

이것이 중요한 이유

PDF 라이브러리는 한 번만 호출하는 렌더 콜이 아닙니다. 그것은 여러분의 문서가 존재하는 한 계속 물려받는 의존성입니다. 그 의존성이 더 이상 움직이지 않으면, 여러분의 문서는 새로운 일을 할 수 없게 됩니다 — 그리고 여러분은 그 사실을 가장 나쁜 순간에, 즉 고객이나 감사인, 또는 규제 기관이 기준을 정할 때 알게 됩니다.

그 벽은 이렇게 생겼습니다. 포맷은 앞으로 나아갔습니다. PDF 2.0이 표준의 현행 판이며 (SpecSpec: ISO 32000-2ISO 32000-2), 1.x 구조에 갇힌 writer는 나머지 툴체인이 전제하는 포맷에 뒤처져 있습니다. 서명은 빈약하거나 덧붙여진 수준이라, 서명이 효력을 갖게 만드는 PAdES 베이스라인 프로파일에는 한참 못 미칩니다(SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). PDF/A 계열로의 보관용 출력과 접근성을 위한 태그 구조는 아예 없거나 취약합니다. 그리고 API 자체에 타입이 없습니다 — 문자열 방향값, 위치로 전달되는 불리언, 우연히 알게 되는 기본값 — 그래서 컴파일러도 리뷰어도 여러분을 도울 수 없습니다.

이 중 어느 것도 우회 패치로 메울 수 있는 버그가 아닙니다. 그것들은 지난 시대를 위해 만들어진 도구의 형태이며, 그러한 도구 중 상당수는 여러분의 문서가 이제 충족해야 하는 표준을 향해 더 이상 적극적으로 나아가지 않습니다.

짧게 요약하면

• 레거시 PHP PDF 라이브러리는 대체로 여전히 돌아갑니다. 문제는 그것들이 현대적 적합성을 온전히 갖춘 채로 통상적으로 생산하지 못하는 것입니다. PDF 2.0, 베이스라인에 부합하는 서명, 검증된 PDF/A, 태그 기반 접근성 — 이름을 거론한 라이브러리들에서의 지원은 제한적이거나 부재합니다.
• NextPDF는 기본값으로 PDF 2.0을 기록하는 PHP 8.4 엔진이며, 엄격한 타입, 보관용 프로파일, 그리고 일급 출력으로서의 PAdES 서명을 갖추고 있습니다.
• 첫날부터 전부 다시 작성할 필요는 없습니다. TCPDF 호환 표면은 익숙한 호출이 계속 작동하게 하면서, 동시에 중요한 문서 로직을 옮길 수 있게 해 줍니다.
• 그 표면은 TCPDF와 호환되지만, 바이트 단위로 동일하지는 않습니다. 그것은 마이그레이션을 가로지르는 다리이며, 문서화된 동작상의 차이를 동반합니다 — 모든 스크립트가 그대로 돌아간다는 주장이 아닙니다.
• 정직한 시험대는 새 역량이 그 이동의 가치만큼 되는가입니다. 어떤 워크로드에는 그렇지 않으며, 우리는 그것을 분명히 말합니다.

NextPDF가 이를 다루는 방식

접근법은 마이그레이션을 도약이 아니라 순서로 만드는 것입니다. 여러분은 그 과정 내내 문서를 계속 생산하며, 빅뱅 방식의 재작성에 한 번의 릴리스를 거는 대신 옛 제약을 하나씩 교체해 나갑니다.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0은 기능 플래그가 아니라 기준선입니다. NextPDF는 기본값으로 포맷의 현행 판을 기록하며(SpecSpec: ISO 32000-2ISO 32000-2), 프로파일이 요구하면 더 오래된 구조도 직렬화할 수 있습니다. 1.x 구조에 동결된 라이브러리는 이 지점에서 여러분을 따라올 수 없습니다. 그것은 빠뜨린 설정이 아니라, 그 라이브러리가 앞선 시대의 것이기 때문입니다.

보관성과 접근성은 writer의 속성입니다. 검증기가 PDF/A로 받아들이는 파일을 생산하는 것은 엔진이 기록하면서 해내야 하는 일입니다 — 나중에 덧대어 붙일 수 없습니다 (SpecSpec: ISO 19005-4ISO 19005-4). PDF를 접근 가능하게 만드는 태그 구조도 마찬가지입니다. NextPDF는 이를 생성 과정에서 만들어 내며, 이것이 바로 많은 레거시 도구가 밟을 수 없는 — 또는 검증기가 받아들이는 수준에 못 미친 채 부분적으로만 밟는 — 단계입니다.

서명은 베이스라인 기준을 통과합니다. PDF에서의 고급 전자 서명은 PAdES 프로파일을 따르며(SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), 그 다이제스트는 선언된 바이트 범위를 다루고 서명은 검증기가 확인하는 메타데이터를 지닙니다. 덧붙인 서명 보조 도구는 그 기준에 좀처럼 이르지 못합니다. NextPDF는 이를 사후 보강이 아니라 일급 출력으로 취급합니다.

호환 표면은 다리이며, 정직하게 명시되어 있습니다. TCPDF 호환 계층은 여러분이 중요한 부분을 마이그레이션하는 동안 기존 호출 지점이 계속 문서를 생산하도록 존재합니다. 그것은 모든 NextPDF 마이그레이션 가이드와 같은 모델을 따릅니다. 원본 라이브러리와 호환되되, 바이트 단위로 동일하지는 않으며, 동작상의 차이가 기록되어 있습니다. 그 정직함이 핵심입니다 — 조용한 “99% 끼워 넣기” 주장은 바로 이 엔진이 거부하도록 만들어진 종류의 추측입니다.

Human-factors note:Human-factors note

마이그레이션을 해야 하는 이유는 오늘 가진 코드인 경우는 드뭅니다. 그것은 내일 요청받게 될 문서입니다. 유지보수성은 명명된 품질 속성으로 — 필요가 바뀔 때 시스템을 얼마나 수월하게 분석하고 변경할 수 있는가입니다 (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). 더 이상 움직이지 않는 의존성은 그것을 조용히 갉아먹으며, 여러분은 새 요구 사항이 도착하고 그 답이 “여기서는 안 됩니다”가 되어야 할 때에야 비로소 그 대가를 느낍니다. 단계적 이동은 문서가 계속 흐르는 동안, 마감 압박 속에 한꺼번에 치르는 대신, 그 대가를 여러분의 일정에 맞춰 치르게 합니다.

실제 예시

마이그레이션의 형태는 호출 지점에서는 작습니다. 옛 코드는 호환 표면을 통해 계속 파일을 생산하고, 새 코드는 타입이 있는 네이티브 API를 통해 의도를 명시하며 레거시 라이브러리가 이르지 못하거나 제한된 적합성으로만 이르는 출력을 요청합니다.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

첫 번째 블록은 발판입니다. 문서가 계속 흐르게 하기 위해 여러분의 애플리케이션에서 바꿔야 할 것은 아무것도 없습니다. 두 번째는 목적지입니다. “세로 방향”, “문자열 출력”, 그리고 폰트가 명시적인 타입 호출이며, 거기서는 보관성, 서명, 접근성이 여러분이 부딪히는 벽이 아니라 켤 수 있는 출력이 됩니다.

흔한 오해

흔한 기대는 “내 옛 라이브러리가 PDF 2.0과 서명을 하도록 만드는 플래그가 분명히 있을 것이다”입니다. 없습니다. 이것들은 성숙한 라이브러리가 노출하기를 잊은 옵션이 아닙니다. 그것들은 그 아키텍처가 애초에 중심에 두고 만들어지지 않은 역량입니다. writer가 구현하지 않은 포맷 판이나 서명 프로파일을 설정으로 만들어 낼 수는 없습니다.

거울에 비친 듯한 반대편의 오해는 NextPDF가 100% TCPDF 끼워 넣기여서 마이그레이션이 공짜라는 것입니다. 그렇지 않으며, 우리는 그렇지 않은 척하지 않습니다. 호환 표면은 이동을 가로질러 여러분을 옮겨 주기 위해 API의 실제로 문서화된 일부를 다룹니다. 일부 호출은 다르게 동작하고, 몇몇은 범위 밖입니다. 그것을 모든 레거시 스크립트가 손대지 않고 돌아간다는 보장이 아니라, 공개된 지도를 갖춘 다리로 다루세요.

한계와 경계

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ 호환 표면은 TCPDF와 호환되지만, 바이트 단위로 동일하지는 않습니다. 그것은 마이그레이션 동안 기존 호출 지점이 계속 파일을 생산하도록 API의 문서화된 하위 집합을 다룹니다. 그것은 다리이지 끼워 넣기가 아닙니다. 일부 동작은 다르고 일부 호출은 지원되지 않으며, 모두 메서드 커버리지 및 마이그레이션 페이지에 나열되어 있습니다. 목적지는 표준 등급 출력이 자리하는, 타입이 있는 네이티브 API입니다.
Pro	●Available
Enterprise	●Available

마이그레이션은 미덕이 아니라 수단입니다. 여러분의 문서가 단순하고, 라이브러리가 여전히 유지보수되며, PDF 2.0, 서명, PDF/A, 접근성이 결코 필요하지 않을 것이라면, 정직한 답은 지금 자리에 머무는 것일 수 있습니다 — 전환 비용은 실재하며, 필요하지 않은 이동은 하지 말아야 할 이동입니다. NextPDF를 사용하지 말아야 할 때 페이지가 그 선을 주저 없이 긋습니다.

이 페이지는 마이그레이션 경로와 엔진의 목표를 설명합니다. 정확한 API 커버리지, 동작상의 차이, 그리고 단계별 절차는 호환 문서에 있으며, 각 호출이 무엇을 하는지에 대한 권위는 거기에 있습니다. 여기 있는 어떤 것도 임의의 레거시 스크립트가 그대로 돌아간다고 약속하지 않습니다.

관련 문서

• PDF 2.0이 바꾼 것 — 많은 레거시 라이브러리가 내보낼 수 없는 포맷 판과, 그것이 왜 중요한지.
• TCPDF 호환 표면 — 다리가 무엇을 다루고 어디서 달라지는지에 대한 권위 있는 가이드.
• NextPDF를 사용하지 말아야 할 때 — 정직한 경계, 그래서 필요하지 않은 마이그레이션은 건너뛸 수 있습니다.
• 하나의 엔진, 모든 프레임워크 — 여러분이 마이그레이션해 가는 엔진이 이미 운영 중인 스택에 어디서 연결되는지.

용어집

• PDF 2.0 — 휴대용 문서 포맷 표준의 현행 판 (ISO 32000-2). 처음 등장할 때 풀어 씀. NextPDF가 기본값으로 기록하는 포맷.
• PDF/A — PDF를 장기적으로 안전하게 보존하는 기준을 정의하는 보관용 적합성 계열 (ISO 19005 시리즈). writer가 생산해야 하는 속성이지, 호출자가 나중에 추가할 수 있는 것이 아닙니다.
• PAdES — PDF 고급 전자 서명(PDF Advanced Electronic Signatures), PDF에 표준 등급 서명을 내장하기 위한 ETSI 프로파일 계열(EN 319 142). 처음 등장할 때 풀어 씀. 서명 페이지에서 자세히 다룹니다.
• 호환 표면 — 원본 라이브러리(여기서는 TCPDF)의 형태를 본떠 만든 API 계층으로, 기존 호출 지점이 마이그레이션 동안 계속 작동하게 합니다. 원본과 호환되되, 바이트 단위로 동일하지는 않은 — 끼워 넣기가 아니라 다리입니다.
• 끼워 넣기 대체(drop-in replacement) — 기존 코드를 손대지 않고 돌리는 대체물. TCPDF 호환 표면은 의도적으로 이렇게 설명되지 않습니다. 그것은 알려진 동작상의 차이를 동반하는, 문서화된 마이그레이션 보조 도구입니다.