Membangun Ekstensi

Arsitektur TCPDF-Next terbuka secara desain. Enam ekstensi resmi (Artisan, Pro, Laravel, Symfony, CodeIgniter, Adaptation) menggunakan interface dan hook point yang sama yang tersedia untuk developer pihak ketiga mana pun.

Kontrak Interface

Ekstensi Anda harus mengimplementasikan satu atau lebih interface ini:

PdfDocumentInterface

Kontrak dokumen inti. Implementasikan ini jika Anda membangun engine dokumen alternatif.

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

Implementasikan ini untuk backend signing kustom (cloud HSM, layanan remote signing, dll.).

namespace Yeeefang\TcpdfNext\Contracts;

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

HsmSignerInterface

Untuk integrasi 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

Untuk strategi pemuatan font kustom:

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

Skeleton Ekstensi

Berikut ekstensi pihak ketiga minimal:

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 Ekstensi

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

Cara Ekstensi Resmi Terhubung

Fungsional

Artisan → Core

Chrome renderer di-inject via setChromeRendererConfig() pada class Document. Core menyimpan renderer sebagai ?object — tanpa dependensi type pada Artisan.

Pro → Core

Class Pro seperti LtvManager dan PdfAManager beroperasi pada BinaryBuffer dan ObjectRegistry — API internal yang sama yang digunakan Core. PadesOrchestrator menerima parameter opsional khusus Pro (CertificateChainValidator, OcspResponseVerifier).

Integrasi Framework

Laravel → Core

ServiceProvider membuat factory binding untuk PdfDocumentInterface yang mengembalikan instance Document yang terkonfigurasi. Facade mem-proxy panggilan statis ke instance yang di-resolve container.

Symfony → Core

TcpdfNextBundle mendaftarkan PdfFactory sebagai service. Inject via constructor injection atau atribut #[Autowire]. Integrasi Messenger mendispatch GeneratePdfMessage untuk pembuatan async.

CodeIgniter → Core

TcpdfNextService mendaftar di service container CodeIgniter. Gunakan service('tcpdfnext') atau inject via PdfLibrary di controller. Integrasi queue menggunakan task scheduler CodeIgniter.

Kompatibilitas

Adaptation → Core

Class adapter TCPDF meng-extend base non-final, memetakan semua 252 method legacy ke padanan TCPDF-Next. Override Header() dan Footer() berfungsi apa adanya. Class helper legacy (TCPDF_STATIC, TCPDF_FONTS, TCPDF_COLORS, TCPDF_IMAGES) mendelegasikan ke API modern.

Konvensi Namespace

Ikuti pola ekosistem:

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

Gunakan interface Yeeefang\TcpdfNext\Contracts\, jangan pernah class internal Core\, untuk batas API publik Anda.