Xây dựng extension

Kiến trúc TCPDF-Next mở theo thiết kế. Sáu extension chính thức (Artisan, Pro, Laravel, Symfony, CodeIgniter, Adaptation) dùng cùng interface và hook point có sẵn cho bất kỳ lập trình viên bên thứ ba.

Interface Contract

Extension của bạn nên implement một hoặc nhiều interface sau:

PdfDocumentInterface

Contract document cốt lõi. Implement nếu bạn xây engine document thay thế.

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

Implement cho backend ký tùy chỉnh (cloud HSM, dịch vụ ký từ xa, v.v.).

namespace Yeeefang\TcpdfNext\Contracts;

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

HsmSignerInterface

Cho tích hợp hardware security module:

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

Cho chiến lược tải font tùy chỉnh:

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;
}

Khung extension

Đây là extension bên thứ ba tối thiểu:

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/"
        }
    }
}

Class Extension

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();
    }
}

Cách extension chính thức kết nối

Chức năng

Artisan -> Core

Chrome renderer được inject qua setChromeRendererConfig() trên class Document. Core lưu renderer dạng ?object — không dependency kiểu vào Artisan.

Pro -> Core

Class Pro như LtvManager và PdfAManager thao tác trên BinaryBuffer và ObjectRegistry — cùng API nội bộ Core dùng.

Tích hợp Framework

Laravel -> Core

ServiceProvider tạo factory binding cho PdfDocumentInterface trả về instance Document đã cấu hình. Facade proxy lời gọi static tới instance resolve từ container.

Symfony -> Core

TcpdfNextBundle đăng ký PdfFactory dạng service. Inject qua constructor injection hoặc attribute #[Autowire].

CodeIgniter -> Core

TcpdfNextService đăng ký trong service container của CodeIgniter. Dùng service('tcpdfnext') hoặc inject qua PdfLibrary trong controller.

Tương thích

Adaptation -> Core

Class adapter TCPDF extends base non-final, ánh xạ mọi 252 method cũ sang tương đương TCPDF-Next. Override Header() và Footer() hoạt động như trước.

Quy ước Namespace

Theo pattern hệ sinh thái:

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

Dùng interface Yeeefang\TcpdfNext\Contracts\, không bao giờ class nội bộ Core\, cho ranh giới public API.