接口参考

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 — 接口方法中引用的值对象