확장 빌드하기

TCPDF-Next의 아키텍처는 설계상 개방되어 있습니다. 세 가지 공식 확장(Artisan, Laravel, Pro)은 모든 서드파티 개발자가 사용할 수 있는 동일한 인터페이스와 훅 포인트를 사용합니다.

인터페이스 계약

확장은 다음 인터페이스 중 하나 이상을 구현해야 합니다:

PdfDocumentInterface

핵심 문서 계약입니다. 대안적인 문서 엔진을 빌드하는 경우 이 인터페이스를 구현하세요.

namespace Yeeefang\TcpdfNext\Contracts;

interface PdfDocumentInterface
{
    public function addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait): static;
    public function setMargins(Margin $margin): static;
    public function setFont(string $family, string $style = '', float $size = 12.0): static;
    public function cell(float $width, float $height, string $text = '', ...): static;
    public function multiCell(float $width, float $height, string $text, ...): static;
    public function writeHtml(string $html): static;
    public function image(string $file, ...): static;
    public function output(?string $filename = null, OutputDestination $dest = OutputDestination::Inline): string;
    public function save(string $path): void;
}

SignerInterface

커스텀 서명 백엔드(클라우드 HSM, 원격 서명 서비스 등)를 위해 이 인터페이스를 구현하세요.

namespace Yeeefang\TcpdfNext\Contracts;

interface SignerInterface
{
    public function sign(string $data): SignatureResult;
    public function timestamp(string $signatureValue): string;
    public function supportsLtv(): bool;
}

HsmSignerInterface

하드웨어 보안 모듈 통합을 위한 인터페이스입니다:

namespace Yeeefang\TcpdfNext\Contracts;

interface HsmSignerInterface
{
    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string;
    public function getCertificateDer(): string;
    public function getCertificateChainDer(): array;
    public function getPublicKeyAlgorithm(): string;
}

FontManagerInterface

커스텀 폰트 로딩 전략을 위한 인터페이스입니다:

namespace Yeeefang\TcpdfNext\Contracts;

interface FontManagerInterface
{
    public function registerFont(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo;
    public function getFont(string $family, string $style = ''): ?FontInfo;
    public function subset(FontInfo $font, string $text): string;
    public function getRegisteredFonts(): array;
    public function addFontDirectory(string $directory): void;
}

확장 스켈레톤

다음은 최소한의 서드파티 확장 예제입니다:

composer.json

{
    "name": "your-vendor/tcpdf-next-watermark",
    "description": "Advanced watermark extension for TCPDF-Next",
    "type": "library",
    "require": {
        "php": "^8.5",
        "yeeefang/tcpdf-next": "^1.7"
    },
    "autoload": {
        "psr-4": {
            "YourVendor\\TcpdfNextWatermark\\": "src/"
        }
    }
}

확장 클래스

namespace YourVendor\TcpdfNextWatermark;

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Graphics\Color;

final class WatermarkExtension
{
    public function apply(
        Document $document,
        string $text,
        float $angle = 45.0,
        float $opacity = 0.15,
    ): Document {
        return $document
            ->startTransform()
            ->setAlpha($opacity)
            ->rotate($angle, $document->getPageWidth() / 2, $document->getPageHeight() / 2)
            ->setFontSize(60)
            ->setTextColor(200, 200, 200)
            ->text(
                $document->getPageWidth() / 4,
                $document->getPageHeight() / 2,
                $text,
            )
            ->stopTransform();
    }
}

공식 확장의 연결 방식

Artisan → Core

Chrome 렌더러는 Document 클래스의 setChromeRendererConfig()을 통해 주입됩니다. Core는 렌더러를 ?object로 저장합니다 — Artisan에 대한 타입 의존성이 없습니다.

Laravel → Core

ServiceProvider는 설정된 Document 인스턴스를 반환하는 PdfDocumentInterface용 팩토리 바인딩을 생성합니다. Facade는 컨테이너에서 해결된 인스턴스로 정적 호출을 프록시합니다.

Pro → Core

LtvManager와 PdfAManager 같은 Pro 클래스는 BinaryBuffer와 ObjectRegistry에서 작동합니다 — Core가 사용하는 것과 동일한 내부 API입니다. PadesOrchestrator는 선택적 Pro 전용 매개변수(CertificateChainValidator, OcspResponseVerifier)를 받습니다.

네임스페이스 규칙

에코시스템 패턴을 따르세요:

YourVendor\TcpdfNext{ExtensionName}\
├── YourMainClass.php
├── Config\
├── Exception\
└── ...

공개 API 경계에는 Core\ 내부 클래스가 아닌 Yeeefang\TcpdfNext\Contracts\ 인터페이스를 사용하세요.