compat-legacy 구성

한눈에 보기

이 어댑터는 세 가지 방식으로 구성할 수 있습니다.

엄격 모드 — 조용히 발생하는 매개변수 손실을 예외로 전환하는 감사용 토글입니다. 기본값은 꺼짐입니다.
레거시 상수 — TCPDF K_* / PDF_* 상수로, 이를 읽는 레거시 코드가 계속 동작하도록 6.2.13 기본값으로 자동 정의됩니다.
AdaptationConfig — 상수 기반 구성을 대체하는 최신 불변 구성 객체입니다.

대부분의 문서 구성은 이미 호출하고 있는 동일한 TCPDF 메서드(SetMargins(), SetFont() 등)를 통해 이루어집니다. 아래 항목은 호환성 계층에 특화된 내용만 다룹니다.

엄격 모드

엄격 모드는 마이그레이션에서 가장 중요한 설정입니다. 렌더링된 출력은 변경하지 않습니다. TCPDF 동작을 재현할 수 없는 호출이 명확하게 실패할지 아니면 조용히 저하될지를 제어합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php가 검증하는 동작은 다음과 같습니다.

모드	조용히 무시되는 메서드 호출	결과
꺼짐(기본값)	e.g. 추가 매개변수를 전달한 `Image()`	실행되며, 무시된 매개변수는 효과가 없습니다
켜짐	동일한 호출	무시된 매개변수를 명시하는 `TcpdfNotImplementedException` 예외를 던집니다
켜짐	지원되는 매개변수만 전달한, 조용히 무시될 수 있는 메서드 호출	던지지 않습니다(e.g. `SetProtection([], 'u', 'o', 0, [])`)

엄격 모드는 동작을 덧붙이는 방식으로 적용됩니다. 메서드가 매개변수를 실제로 지원하는 경우 해당 위임은 그대로 수행되며, 엄격 모드는 누락되는 매개변수에 대해서만 예외 가드를 추가합니다. 권장 사용처는 프로덕션이 아니라 전용 CI 작업 또는 일회성 감사 패스입니다. 이는 OWASP ASVS 5.0 오류 처리의 명시적 실패 원칙(RAG 사이드카에 기록된 reference_id 절)에 따른 것입니다. 호출자는 자신의 의도가 존중되지 않았을 때 이를 관찰할 수 있어야 합니다.

엄격 모드를 켠 채로 프로덕션 코드를 출시하지 마십시오. 조용히 무시된 매개변수는 런타임 결함이 아니라 개발자 경험 문제입니다. 프로덕션 렌더링 경로에서 발생하는 예외는 저하된 출력보다 나쁩니다. 감사한 뒤 수정하고 끄십시오 — /integrations/tcpdf-compat/migration/를 참고하십시오.

레거시 TCPDF 상수

레거시 TCPDF는 K_* 및 PDF_* 상수에서 구성을 읽습니다. 어댑터는 아직 정의되지 않은 경우에만 생성 시점에 TCPDF 6.2.13 기본값을 사용하여 이를 자동 정의합니다. 애플리케이션이 이미 상수를 정의한 경우(예: 사용자 정의 K_PATH_FONTS), 해당 값은 보존됩니다.

주요 기본값(전체 목록: src/Compat/Tcpdf/Config/LegacyDefaults.php):

상수	기본값	비고
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	사용자 단위
`PDF_MARGIN_TOP`	`27`	사용자 단위
`PDF_MARGIN_BOTTOM`	`25`	사용자 단위
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	강화됨 — 항상 false이며, 마크업이 PHP 실행을 유발할 수 없습니다
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	강화됨 — `Error()`는 항상 예외를 던지며, 절대 `die()`하지 않습니다
`K_TIMEZONE`	`UTC`

이 중 두 가지는 안전을 위해 의도적으로 고정되어 있으며 구성을 통해 완화할 수 없습니다: K_TCPDF_CALLS_IN_HTML은 항상 false이고, K_TCPDF_THROW_EXCEPTION_ERROR은 사실상 항상 true입니다. 레거시 코드가 두 가지 안전하지 않은 레거시 동작 중 하나에 의존하는 경우 해당 코드를 변경해야 합니다 — /integrations/tcpdf-compat/security-and-operations/를 참고하십시오.

자체 상수를 정의하려면 첫 번째 어댑터를 생성하기 전에(일반적으로 애플리케이션 부트스트랩에서) 정의하십시오.

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

구성 해석 순서

문서를 생성할 때 어댑터는 다음 순서로 구성을 해석합니다(뒤 단계는 앞 단계를 재정의하지 않습니다).

생성자 인수(orientation, unit, format, …) — 해당 인수가 다루는 값에 대해 가장 높은 우선순위입니다.
애플리케이션이 이미 정의한 레거시 상수입니다.
아직 정의되지 않은 모든 상수는 LegacyDefaults가 TCPDF 6.2.13 기본 상수로 자동 정의합니다.

생성자 인수 unicode, encoding, diskcache는 시그니처 호환성을 위해 허용되지만 효과가 없습니다. NextPDF는 항상 유니코드 및 UTF-8이며, 디스크 기반 페이지 캐시가 없습니다. pdfa 생성자 플래그도 허용되지만, PDF/A 보관 적합성에는 상용 에디션이 필요합니다(/integrations/tcpdf-compat/security-and-operations/ 참고).

함께 보기

src/Compat/Tcpdf/Config/LegacyDefaults.php — 기준이 되는 상수 기본값
src/Compat/Tcpdf/Config/AdaptationConfig.php — 최신 구성 객체
/integrations/tcpdf-compat/migration/ — 전역 상수에서 구성 이전하기
/integrations/tcpdf-compat/security-and-operations/ — 강화되어 구성으로 바꿀 수 없는 두 플래그