NextPDF compat-legacy 설치

한눈에 보기

nextpdf/compat-legacy는 Composer 라이브러리입니다. PHP 8.4 이상과 nextpdf/core ^3.0이 필요합니다. 설치해도 기존 TCPDF 호출은 바뀌지 않으며, 전환에 사용할 수 있는 클래스를 추가할 뿐입니다.

요구 사항

의존성	버전	기준 출처
PHP	`>=8.4 <9.0`	패키지 `composer.jsonrequire.php`
`nextpdf/core`	`^3.0`	패키지 `composer.jsonrequire`
Composer	2.7 이상	툴체인 기준선

이 패키지는 baseline 없이 PHPStan Level 10을 선언하며 자체 테스트 스위트를 제공합니다. 런타임에는 PHP 8.4가 필요합니다. NextPDF 엔진 자체는 백포트 라인을 통해 PHP 8.1부터 8.4까지 지원하지만, 이 어댑터는 PHP 8.4를 하한으로 고정합니다.

설치

Composer로 패키지를 추가합니다:

composer require nextpdf/compat-legacy:^3.0

Composer는 nextpdf/core ^3.0을 전이 의존성으로 해석합니다. 핵심 기능 세트에는 다른 런타임 확장이 필요하지 않습니다.

패키지 메타데이터는 이전 이름 nextpdf/compat-tcpdf에도 Composer replace 항목으로 대응합니다. 새로 설치할 때는 nextpdf/compat-legacy를 require 해야 하며 — 이것이 표준 패키지 이름입니다.

설치 확인

설치 후 어댑터 클래스가 로드되고 엔진 링크가 해석되는지 확인합니다. 다음 검사는 한 페이지짜리 PDF를 전적으로 메모리에서 생성하고 PDF 헤더를 검증합니다 — 이는 패키지 테스트 tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php가 검증하는 것과 동일한 동작 표면입니다.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'compat-legacy install verified');

$bytes = $pdf->Output('verify.pdf', 'S');

if (! str_starts_with($bytes, '%PDF')) {
    fwrite(STDERR, "Install check failed: output is not a PDF.\n");
    exit(1);
}

echo "OK: adapter loaded, engine linked, PDF produced (" . strlen($bytes) . " bytes).\n";

실행합니다:

php examples/install-verify.php

예상 출력은 OK: 줄 하나입니다. 반환된 문자열의 %PDF 접두사는 어댑터가 NextPDF\Core\Document를 생성하고, 페이지 및 텍스트 호출을 위임하며, 유효한 PDF 2.0 출력을 직렬화했음을 확인해 줍니다.

엔진 버전 확인

어댑터에는 nextpdf/core ^3.0이 필요합니다. 해석된 버전을 확인합니다:

composer show nextpdf/core --format=json

Composer가 ^3.0 범위를 벗어난 코어 버전을 해석한 경우, 어댑터는 잘못된 출력을 생성하는 대신 생성 시점에 즉시 실패합니다. 프로젝트가 엔진을 직접 의존성으로도 둔다면, composer.json에 엔진을 명시적으로 고정하십시오.

선택 사항: 전역 클래스 별칭

코드베이스가 전역 네임스페이스에서 new \TCPDF(...)를 호출하지만 아직 해당 use/require 줄을 변경할 수 없다면, 패키지가 전역 별칭을 등록할 수 있습니다. 이는 옵트인 방식이며 /integrations/tcpdf-compat/boot-and-discovery/.에 설명되어 있습니다. 실제 TCPDF 라이브러리가 같은 프로세스에 함께 설치되어 있다면 이를 활성화하지 마십시오 — 충돌 회피 규칙은 /integrations/tcpdf-compat/troubleshooting/를 참조하십시오.

설치로 수행되지 않는 것

기존 TCPDF 의존성을 수정하거나 제거하지 않습니다. tecnickcom/tcpdf 제거는 /integrations/tcpdf-compat/migration/.에서 의도적으로 진행하는 이후 단계입니다.
디지털 서명이나 PDF/A를 활성화하지 않습니다. 이러한 기능은 상용 NextPDF 에디션을 필요로 합니다 (/integrations/tcpdf-compat/security-and-operations/ 참조).
PDF 출력 대상을 변경하지 않습니다. 출력은 항상 PDF 2.0입니다.

다음 단계

/integrations/tcpdf-compat/quickstart/ — 첫 번째 실제 문서를 생성합니다.
/integrations/tcpdf-compat/configuration/ — 엄격 모드와 어댑터 구성.
/integrations/tcpdf-compat/migration/ — 파일 단위 마이그레이션 전략.
/integrations/tcpdf-compat/method-coverage/ — 각 TCPDF 메서드가 여기서 정확히 무엇을 하는지.

참고 자료

패키지 composer.json — 의존성 제약의 권위 있는 기준
docs/TCPDF_COVERAGE.md — 커버리지 매트릭스의 권위 있는 기준 (리포지토리 내)