설계 철학

TCPDF-Next는 TCPDF에서 영감을 받았지만, 모던 PHP 시대를 위해 완전히 처음부터 다시 작성된 라이브러리입니다. 포크도 아니고, 점진적 업그레이드도 아닙니다 — 차세대 아키텍처 위에 구축된 완전히 새로운 라이브러리입니다.

기존 TCPDF는 10년 이상 PHP 커뮤니티에 훌륭하게 기여했습니다. 그러나 단일 파일, 30,000줄 아키텍처로는 현대 PDF 생성의 요구사항을 지원할 수 없습니다: PDF 2.0 준수, PAdES 디지털 서명, PDF/A-4 아카이빙, 또는 Laravel과 같은 프레임워크와의 통합.

TCPDF-Next는 PHP 개발자들이 익숙한 개념 — addPage(), cell(), setFont() — 을 유지하면서 2026년 표준에 맞게 모든 것을 재구축했습니다.

한눈에 보기

	기존 TCPDF	TCPDF-Next
PHP 버전	5.x – 8.x	8.5+ 전용
PDF 사양	1.4 – 1.7	2.0 (ISO 32000-2:2020)
아키텍처	단일 ~30K줄 클래스	213개 파일, 26개 모듈, 12개 조합 가능 트레이트
타입 안전성	없음	PHPStan 레벨 8, Backed 열거형, 읽기 전용 클래스
디지털 서명	기본 PKCS#7	PAdES B-B (Core) → B-LTA (Pro)
아카이빙	PDF/A-1b (부분)	PDF/A-4 (ISO 19005-4:2020)
HTML 렌더링	내장 (제한된 CSS)	내장 + Chrome CDP (완전한 CSS3)
테스트	~50개 테스트	908+ 테스트, 28,881+ 어설션
확장성	모놀리스 서브클래스	모듈형 에코시스템 + 확장 API

에코시스템 아키텍처

TCPDF-Next는 모놀리스가 아닙니다. 각각 명확한 책임을 가진 4개 패키지로 구성된 모듈형 에코시스템입니다:

TCPDF-Next
Core

Artisan
Chrome CDP

Laravel
Framework

Pro
Enterprise

• Core (148개 파일) — PDF 엔진. 문서 생성, 타이포그래피, 바코드, 암호화, PAdES B-B 디지털 서명에 필요한 모든 것이 포함되어 있습니다.
• Artisan (17개 파일) — 픽셀 퍼펙트 HTML/CSS3 렌더링을 위한 Chrome CDP 통합. 래스터화된 이미지가 아닌 Form XObject를 통한 텍스트 선택 가능 PDF 출력.
• Laravel (4개 파일) — 제로 설정 프레임워크 통합. Facade, HTTP 응답, 큐 작업, Octane 안전 바인딩.
• Pro (47개 파일) — 엔터프라이즈 기능. PAdES B-T~B-LTA, PDF/A-4, HSM 서명, 특수 바코드.

확장 API는 개방되어 있습니다: 서드파티 개발자는 공개된 인터페이스(PdfDocumentInterface, SignerInterface, FontManagerInterface, HsmSignerInterface)를 통해 Core에 연결되는 자체 확장을 빌드할 수 있습니다.

12개의 조합 가능 트레이트

Document 클래스는 단일 진입점입니다. 모놀리식 클래스 대신, 12개의 집중된 트레이트로 기능이 구성됩니다:

트레이트	책임
HasMetadata	제목, 저자, 주제, 키워드, 언어
HasPages	페이지 관리, 크기, 여백, 페이지 그룹
HasTypography	폰트 로딩, 크기, 텍스트 장식, RTL, BiDi
HasColors	RGB, CMYK, 별색, 알파, 블렌드 모드
HasTextOutput	cell(), multiCell(), text(), write(), writeHtml()
HasDrawing	도형, 그래디언트, 패턴, SVG, EPS, 이미지
HasTransforms	스케일, 회전, 이동, 기울기, 미러
HasLayout	머리글, 바닥글, 컬럼, 소책자
HasNavigation	북마크, 링크, 목차, 주석, 파일 첨부
HasInteractive	폼 필드, 레이어, 템플릿, JavaScript
HasSecurity	암호화, 디지털 서명, 태그된 PDF, BiDi, 선형화
HasOutput	output(), save(), getPdfData(), 스트리밍

모든 공개 메서드는 플루언트 체이닝을 위해 static을 반환합니다:

$pdf = Document::create()
    ->setTitle('Invoice')       // HasMetadata
    ->addPage()                 // HasPages
    ->setFont('Helvetica', '', 12) // HasTypography
    ->setFillColor(240, 240, 240)  // HasColors
    ->cell(0, 10, 'Hello')     // HasTextOutput
    ->save('invoice.pdf');      // HasOutput

다음 단계

• 아키텍처 심층 분석 — 네임스페이스 맵, 모듈 경계, 지연 초기화
• 확장 빌드하기 — 서드파티 확장을 빌드하는 방법
• 왜 PHP 8.5+인가? — 의도적인 선택과 Docker 가이드