拡張機能の構築

TCPDF-Next のアーキテクチャは設計上オープンです。6 つの公式拡張（Artisan、Pro、Laravel、Symfony、CodeIgniter、Adaptation）は、すべてのサードパーティ開発者が利用できる同じインターフェースとフックポイントを使用しています。

インターフェース契約

拡張機能は以下のインターフェースの 1 つ以上を実装する必要があります：

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 への型依存はありません。

Pro → Core

LtvManager や PdfAManager のような Pro クラスは、Core が使用するのと同じ内部 API である BinaryBuffer と ObjectRegistry を操作します。PadesOrchestrator はオプションの Pro 専用パラメータ（CertificateChainValidator、OcspResponseVerifier）を受け入れます。

フレームワーク統合

Laravel → Core

ServiceProvider は PdfDocumentInterface に対するファクトリバインディングを作成し、設定済みの Document インスタンスを返します。Facade はコンテナで解決されたインスタンスへ静的呼び出しをプロキシします。

Symfony → Core

TcpdfNextBundle は PdfFactory をサービスとして登録します。コンストラクタインジェクションまたは #[Autowire] アトリビュートを通じて注入してください。Messenger 統合は非同期生成のために GeneratePdfMessage をディスパッチします。

CodeIgniter → Core

TcpdfNextService は CodeIgniter のサービスコンテナに登録されます。コントローラでは service('tcpdfnext') を使用するか、PdfLibrary を通じて注入してください。キュー統合は CodeIgniter のタスクスケジューラを使用します。

互換性

Adaptation → Core

TCPDF アダプタークラスは非 final ベースを継承し、252 のレガシーメソッドすべてを TCPDF-Next の同等メソッドにマッピングします。Header() と Footer() のオーバーライドはそのまま動作します。レガシーヘルパークラス（TCPDF_STATIC、TCPDF_FONTS、TCPDF_COLORS、TCPDF_IMAGES）はモダン API に委譲します。

名前空間の規約

エコシステムのパターンに従ってください：

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

パブリック API の境界には Yeeefang\TcpdfNext\Contracts\ インターフェースを使用し、Core\ の内部クラスは絶対に使用しないでください。