TCPDF 호환성 개발자 가이드

한눈에 보기

호환성 어댑터는 마이그레이션 계층입니다. 레거시 동작을 숨기기보다 명확히 드러내야 합니다. 고부가가치 경로를 네이티브 NextPDF API로 이전하는 동안 애플리케이션을 계속 실행 가능한 상태로 유지하는 데 사용하십시오.

레거시 TCPDF 형식의 코드를 유지 관리하거나, 어댑터 커버리지를 추가하거나, 네이티브 NextPDF API로 단계적으로 마이그레이션할 때 이 가이드를 사용하십시오.

아키텍처 경계

계층	소유 주체	책임	여기에 두지 말 것
레거시 애플리케이션	애플리케이션	마이그레이션 중에도 기존 TCPDF 형식 호출이 계속 실행되도록 유지합니다.	네이티브 NextPDF API를 사용해야 하는 새로운 PDF 기능.
어댑터 셸	`nextpdf/compat-legacy`	공유 `TCPDF` 형식 클래스와 호환성 상태를 노출합니다.	대규모 메서드 패밀리 또는 변환 로직.
관심사 트레이트	`nextpdf/compat-legacy`	텍스트, 글꼴, 이미지, 보안, 폼, 페이지 같은 레거시 메서드 패밀리를 그룹화합니다.	패밀리 간 출력 정책.
브리지 클래스	`nextpdf/compat-legacy`	레거시 인수, 대상, 색상, 단위, 형식을 변환합니다.	비즈니스별 동작.
코어 엔진	`nextpdf/nextpdf`	네이티브 문서를 생성합니다.	레거시 호환성 보장 사항.

런타임 수명 주기

단계	동작	개발자 조치
부트스트랩	선택적 레거시 부트스트랩이 호환성 이름을 노출합니다.	레거시 코드에 TCPDF 심볼이 필요한 경우에만 사용하십시오.
생성	레거시 생성자 인수는 코어 문서 구성에 맞게 조정됩니다.	마이그레이션 중에 생성자 입력을 안정적으로 유지하십시오.
메서드 호출	지원되는 메서드는 관심사와 브리지를 통해 NextPDF 동작에 매핑됩니다.	동등성을 가정하기 전에 메서드 커버리지를 확인하십시오.
지원되지 않는 기능	지원되지 않는 동작은 명시적인 호환성 예외를 발생시킵니다.	호출을 교체하거나 애플리케이션 코드 뒤에 격리하십시오.
출력	출력 브리지는 레거시 대상 동작을 NextPDF 출력에 매핑합니다.	파일 이름과 저장소 루트를 검증하십시오.

마이그레이션 인벤토리

애플리케이션의 모든 TCPDF 메서드 호출을 수집하는 것부터 시작하십시오. 동작을 변경하기 전에 각 호출을 분류하십시오.

분류	의미	조치
지원되는 어댑터 메서드	메서드가 지원 대상으로 문서화되어 있고 테스트도 있습니다.	일시적으로 유지한 다음, 해당 영역을 다룰 때 마이그레이션하십시오.
부분적 어댑터 메서드	메서드는 존재하지만 동작이 레거시 TCPDF와 완전히 일치하지는 않습니다.	픽스처 테스트를 추가하고 출력을 수동으로 검증하십시오.
명시적으로 지원되지 않는 메서드	어댑터가 호환성 예외를 발생시킵니다.	네이티브 NextPDF로 교체하거나 기능을 제거하십시오.
비즈니스별 래퍼	애플리케이션이 이미 TCPDF 호출을 래핑하고 있습니다.	래퍼 내부를 먼저 마이그레이션하십시오.
규정 준수에 민감한 호출	서명, 암호화, 태깅, PDF/A, 접근성 또는 인보이스 플로우.	전용 검증과 함께 네이티브 NextPDF API로 마이그레이션하십시오.

어댑터 기여 패턴

해당 동작을 소유하는 가장 작은 메서드 패밀리에 호환성 지원을 추가하십시오.

변경 유형	구현 위치	필수 테스트
텍스트 출력 메서드	`Concerns\AdaptsTextOutput` 또는 글꼴 관심사.	레거시 픽스처와 네이티브 출력 어서션.
페이지 또는 여백 메서드	페이지, 위치 지정 또는 여백 관심사.	좌표 변환 및 페이지 상태 테스트.
이미지 또는 그리기 메서드	이미지, 그리기, 색상 또는 그라디언트 관심사.	입력 검증 및 visual/structural 출력 테스트.
출력 대상	`OutputBridge`.	대상 매핑 및 안전하지 않은 경로 테스트.
지원되지 않는 기능	예외 팩터리 또는 메서드 커버리지 표.	예외 유형 및 메시지 테스트.

관심사 트레이트가 패밀리를 담당한다면 어댑터 셸에 대규모 메서드를 직접 추가하지 마십시오.

네이티브 마이그레이션 패턴

어댑터를 사용하여 안정화한 다음, 안정적인 워크플로를 네이티브 API로 이전하십시오.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

마이그레이션은 작은 동작 단위의 연속적인 이전으로 다루십시오. 고위험 섹션 하나가 네이티브 API로 이전되는 동안에도 페이지는 여전히 어댑터를 사용할 수 있습니다.

확장 지점

확장 지점	용도	제약
`AdaptationConfig`	마이그레이션 중 어댑터 동작을 제어합니다.	기본값은 검토를 거친 명시적 상태로 유지하십시오.
관심사 트레이트	텍스트, 폼, 이미지 또는 보안 같은 메서드 패밀리를 그룹화합니다.	어댑터 셸이 아닌 적절한 관심사에 메서드를 추가하십시오.
브리지 클래스	레거시 인수 형식을 코어 값으로 변환합니다.	브리지 동작을 마이그레이션 테스트로 계속 커버하십시오.
`CompatAdapterInterface`	도구용 어댑터 수준 추상화입니다.	새 코드에서 네이티브 코어 계약의 대체물로 사용하지 마십시오.
메서드 커버리지 표	개발자 대상 지원 현황표입니다.	지원 상태가 변경되면 업데이트하십시오.

마이그레이션 워크플로

어댑터를 설치하고 레거시 테스트 스위트를 변경하지 않고 실행하십시오.
먼저 메서드 커버리지를 열고 호출된 모든 메서드를 분류하십시오.
지원되지 않는 메서드를 먼저 교체하십시오.
대용량 또는 규정 준수에 민감한 경로를 네이티브 코어 API로 이전하십시오.
마이그레이션된 모든 메서드 패밀리에 대해 픽스처 커버리지를 추가하십시오.
애플리케이션 진입점이 더 이상 부트스트랩 별칭에 의존하지 않으면 이를 제거하십시오.

실패 처리

실패	처리 위치	권장 대응
지원되지 않는 메서드	어댑터 예외.	호출을 교체하거나 애플리케이션 어댑터 뒤에 격리하십시오.
부분적 레이아웃 동등성	마이그레이션 테스트 및 시각적 검토.	롤아웃 전에 허용되는 차이를 문서화하십시오.
안전하지 않은 출력 대상	`OutputBridge` 및 애플리케이션 저장소 정책.	안전하지 않은 경로를 거부하고 네이티브 출력 API를 선호하십시오.
보안 기능 불일치	네이티브 마이그레이션 계획.	규제 대상 출력에 대해 호환성 전용 동작을 출시하지 마십시오.
부트스트랩 별칭 충돌	애플리케이션 부트스트랩.	전역 별칭을 제거하거나 범위를 레거시 진입점으로 제한하십시오.

안전한 기본값

관심사	기본값	재정의해야 하는 경우
지원되지 않는 메서드	명시적 예외를 발생시킵니다.	프로덕션에서 이를 약화시키지 마십시오.
레거시 기본값	기본값은 `LegacyDefaults`에 중앙 집중화되어 있습니다.	알려진 마이그레이션 동작에 대해서만 재정의하십시오.
출력 매핑	출력은 `OutputBridge`를 통과합니다.	마이그레이션 후 네이티브 출력 API를 사용하십시오.
커버리지 소스	메서드 커버리지 페이지 및 테스트.	각 어댑터 업그레이드 후에 커버리지 검사를 다시 실행하십시오.
엄격 모드	마이그레이션 감사 중에는 활성화 상태로 유지하십시오.	문서화된 레거시 호환성 기간에 대해서만 비활성화하십시오.

테스트 체크리스트

마이그레이션된 각 메서드 패밀리에 대해 레거시 픽스처를 유지하십시오.
레거시 메서드를 교체하기 전에 네이티브 NextPDF 테스트를 하나 추가하십시오.
지원되지 않는 메서드가 문서화된 예외를 발생시키는지 어서트하십시오.
정확한 바이트 단위 동등성이 현실적인 마이그레이션 목표가 아니라면 출력 구조를 비교하십시오.
어댑터 메서드를 추가하거나 변경한 후 메서드 커버리지 검사를 실행하십시오.
레거시 코드가 사용하는 모든 출력 대상에 대해 저장소 경로 테스트를 추가하십시오.