打造擴充套件

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 渲染器透過 setChromeRendererConfig() 注入到 Document 類別中。Core 將渲染器儲存為 ?object——對 Artisan 沒有型別相依。

Laravel → Core

ServiceProvider 為 PdfDocumentInterface 建立工廠繫結，回傳一個已設定好的 Document 實例。Facade 將靜態呼叫代理到容器解析的實例上。

Pro → Core

Pro 的類別如 LtvManager 和 PdfAManager 操作的是 BinaryBuffer 和 ObjectRegistry——與 Core 自身使用的內部 API 相同。PadesOrchestrator 接受可選的 Pro 專屬參數（CertificateChainValidator、OcspResponseVerifier）。

命名空間慣例

遵循生態系的慣例：

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

公開 API 邊界請使用 Yeeefang\TcpdfNext\Contracts\ 的介面，不要使用 Core\ 的內部類別。