介面參考

TCPDF-Next 透過介面（Interface）定義模組之間的合約，確保鬆散耦合與實作的可替換性。以下為四個核心公開介面的完整定義。

命名空間：TcpdfNext\Contracts

---

PdfDocumentInterface

文件操作的頂層合約。Document 類別實作此介面。當您需要在自己的程式碼中以型別提示接收文件物件時，請使用此介面而非具體類別。

namespace TcpdfNext\Contracts;

interface PdfDocumentInterface
{
    /** 建立新的文件實例。 */
    public static function create(?Config $config = null): static;

    /** 新增頁面。 */
    public function addPage(
        ?PageSize $size = null,
        ?Orientation $orientation = null
    ): static;

    /** 取得目前頁碼（從 1 開始）。 */
    public function getCurrentPage(): int;

    /** 取得總頁數。 */
    public function getTotalPages(): int;

    /** 設定文件標題。 */
    public function setTitle(string $title): static;

    /** 設定文件作者。 */
    public function setAuthor(string $author): static;

    /** 設定文件語言。 */
    public function setLanguage(string $lang): static;

    /** 在指定座標輸出文字。 */
    public function text(string $text, float $x, ?float $y = null): static;

    /** 設定目前字型。 */
    public function setFont(string $family, float $size = 12, string $style = ''): static;

    /** 儲存文件到指定路徑。 */
    public function save(string $filepath): void;

    /** 取得文件的原始 PDF 位元組。 */
    public function toString(): string;

    /** 輸出文件。 */
    public function output(
        string $name = 'document.pdf',
        OutputDestination $dest = OutputDestination::Inline
    ): string|void;
}

使用場景

use TcpdfNext\Contracts\PdfDocumentInterface;

class InvoiceGenerator
{
    public function generate(PdfDocumentInterface $doc): void
    {
        $doc->setTitle('發票')
            ->addPage()
            ->setFont('NotoSansTC', size: 14, style: 'B')
            ->text('電子發票', x: 70, y: 20);
    }
}

---

FontManagerInterface

字型管理合約。定義字型載入、快取與查詢的標準行為。您可以實作此介面來替換內建的字型管理器，例如使用外部字型服務。

namespace TcpdfNext\Contracts;

interface FontManagerInterface
{
    /** 建立字型管理器實例。 */
    public static function create(): static;

    /** 新增字型搜尋目錄。 */
    public function addFontDir(string $path): static;

    /** 載入字型檔案。 */
    public function loadFont(
        string $name,
        string $file,
        string $style = 'normal'    // 'normal' | 'bold' | 'italic' | 'bolditalic'
    ): static;

    /** 設定字型快取目錄。 */
    public function setCacheDir(string $path): static;

    /** 設定快取存活時間（秒）。 */
    public function setCacheTtl(int $seconds): static;

    /** 檢查指定字型是否已載入。 */
    public function hasFont(string $name, string $style = 'normal'): bool;

    /** 取得指定字型的中繼資料。 */
    public function getFontMetrics(string $name, string $style = 'normal'): FontMetrics;

    /** 取得所有已載入的字型名稱。 */
    public function getLoadedFonts(): array;
}

使用場景

use TcpdfNext\Contracts\FontManagerInterface;
use TcpdfNext\Document;

class CustomFontManager implements FontManagerInterface
{
    // 實作所有方法...
    // 例如從雲端字型服務載入字型
}

$fontManager = new CustomFontManager();
$fontManager->loadFont(name: 'MyBrandFont', file: 'brand.ttf');

$doc = Document::create(fontManager: $fontManager);

---

SignerInterface

數位簽章合約。定義使用軟體憑證（PEM 檔案）進行 PDF 簽章的標準行為。

namespace TcpdfNext\Contracts;

interface SignerInterface
{
    /**
     * 對資料進行 CMS 簽章。
     *
     * @param string $data        待簽章的原始資料
     * @param string $certificate PEM 格式的簽署者憑證
     * @param string $privateKey  PEM 格式的私鑰
     * @param string|null $password 私鑰密碼（若有加密）
     * @return string DER 編碼的 CMS SignedData
     */
    public function sign(
        string $data,
        string $certificate,
        string $privateKey,
        ?string $password = null
    ): string;

    /**
     * 取得簽章使用的雜湊演算法。
     */
    public function getHashAlgorithm(): HashAlgorithm;

    /**
     * 設定簽章使用的雜湊演算法。
     */
    public function setHashAlgorithm(HashAlgorithm $algorithm): static;

    /**
     * 估算簽章資料的最大長度（位元組）。
     * Writer 需要此值來預留簽章空間。
     */
    public function estimateSignatureLength(): int;
}

使用場景

use TcpdfNext\Contracts\SignerInterface;

class AuditableSigner implements SignerInterface
{
    public function __construct(
        private SignerInterface $inner,
        private AuditLogger $logger
    ) {}

    public function sign(
        string $data,
        string $certificate,
        string $privateKey,
        ?string $password = null
    ): string {
        $this->logger->log('簽章操作開始');
        $result = $this->inner->sign($data, $certificate, $privateKey, $password);
        $this->logger->log('簽章操作完成');
        return $result;
    }

    // ... 實作其餘方法
}

---

HsmSignerInterface

HSM（硬體安全模組）簽章合約。繼承 SignerInterface，額外定義與硬體簽章裝置互動的方法。適用於企業級場景，私鑰永遠不離開 HSM。

namespace TcpdfNext\Contracts;

interface HsmSignerInterface extends SignerInterface
{
    /**
     * 使用 HSM 中的金鑰進行簽章。
     * 私鑰不以字串形式提供，而是透過 HSM 的金鑰識別碼引用。
     *
     * @param string $data      待簽章的原始資料
     * @param string $keyId     HSM 中的金鑰識別碼
     * @param string $certificate PEM 格式的簽署者憑證
     * @return string DER 編碼的 CMS SignedData
     */
    public function signWithHsm(
        string $data,
        string $keyId,
        string $certificate
    ): string;

    /**
     * 測試與 HSM 的連線是否正常。
     */
    public function ping(): bool;

    /**
     * 取得 HSM 中可用的金鑰清單。
     *
     * @return array<string, array{id: string, algorithm: string, label: string}>
     */
    public function listKeys(): array;
}

使用場景

use TcpdfNext\Contracts\HsmSignerInterface;

// 例如整合 AWS CloudHSM 或 Azure Key Vault
class AwsCloudHsmSigner implements HsmSignerInterface
{
    public function __construct(
        private string $hsmClusterId,
        private string $region
    ) {}

    public function signWithHsm(
        string $data,
        string $keyId,
        string $certificate
    ): string {
        // 透過 AWS SDK 呼叫 CloudHSM 進行簽章
        // 私鑰永遠不離開 HSM
    }

    // ... 實作其餘方法
}

---

介面繼承關係

SignerInterface
    └── HsmSignerInterface

PdfDocumentInterface 與 FontManagerInterface 為獨立介面，無繼承關係。

---

相關頁面

• Document API — Document 類別實作 PdfDocumentInterface
• 列舉參考 — 介面方法中引用的列舉型別
• 值物件 API — 介面方法中引用的值物件