Referensi Interface

Modul Contracts (TcpdfNext\Contracts) mendefinisikan interface bersama yang digunakan semua modul TCPDF-Next sebagai acuan. Dengan bergantung pada kontrak alih-alih class konkret, Anda bisa mengganti test double, membuat implementasi alternatif, dan mempertahankan API publik yang stabil lintas versi major.

---

PdfDocumentInterface

Namespace: TcpdfNext\Contracts\PdfDocumentInterface

Kontrak API utama yang diimplementasikan oleh Document. Class apa pun yang memenuhi interface ini bisa digunakan sebagai pengganti langsung untuk model dokumen built-in.

Method

pageSize(PageSize $size): static

Set ukuran halaman default untuk halaman baru.

orientation(Orientation $orientation): static

Set orientasi halaman default.

margin(Margin $margin): static

Set margin halaman default.

metadata(?string $title = null, ?string $author = null, ?string $subject = null, ?string $keywords = null, ?string $creator = null): static

Set metadata level dokumen. Semua parameter opsional; berikan hanya yang ingin Anda atur.

addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static

Tambah halaman baru, opsional override default untuk halaman ini.

font(string $family, float $size = 12.0, string $style = ''): static

Pilih font berdasarkan nama family, ukuran, dan style.

text(string $content): static

Tulis baris teks pada posisi kursor saat ini.

output(OutputDestination $destination = OutputDestination::String, ?string $filename = null, ?string $path = null): string|bool

Render PDF ke destinasi yang dipilih.

currentPage(): int

Kembalikan nomor halaman saat ini (1-based).

pageCount(): int

Kembalikan jumlah total halaman.

Contoh

use TcpdfNext\Contracts\PdfDocumentInterface;
use TcpdfNext\Contracts\OutputDestination;

function generateReport(PdfDocumentInterface $pdf): string
{
    return $pdf
        ->addPage()
        ->font('Helvetica', size: 14)
        ->text('Quarterly Report')
        ->output(OutputDestination::String);
}

---

FontManagerInterface

Namespace: TcpdfNext\Contracts\FontManagerInterface

Mendefinisikan loading font, registrasi, subsetting, dan pencarian metrik. FontManager built-in mengimplementasikan interface ini, tetapi Anda bisa menyediakan implementasi kustom untuk sumber font khusus.

Method

registerFont(string $path, string $alias = ''): static

Daftarkan file font TrueType atau OpenType. Jika alias kosong, nama font family dari file digunakan.

hasFont(string $family, string $style = ''): bool

Periksa apakah kombinasi font family dan style tersedia.

getFont(string $family, string $style = ''): FontInfo

Kembalikan objek FontInfo readonly dengan metrik untuk font yang ditentukan.

stringWidth(string $text, string $family, float $size, string $style = ''): float

Hitung lebar string dalam unit user.

subset(string $family, string $style, string $chars): string

Buat binary font subset yang hanya berisi glyph yang diperlukan untuk karakter yang diberikan.

registeredFamilies(): array

Kembalikan daftar semua nama font family yang terdaftar.

Contoh

use TcpdfNext\Contracts\FontManagerInterface;

function addCustomFonts(FontManagerInterface $fonts): void
{
    $fonts->registerFont('/fonts/NotoSans-Regular.ttf', 'NotoSans');
    $fonts->registerFont('/fonts/NotoSans-Bold.ttf', 'NotoSans');

    if ($fonts->hasFont('NotoSans', 'B')) {
        $info = $fonts->getFont('NotoSans', 'B');
        echo "Ascender: {$info->ascender}";
    }
}

---

SignerInterface

Namespace: TcpdfNext\Contracts\SignerInterface

Mendefinisikan kontrak untuk penyedia tanda tangan digital apa pun. Implementasikan interface ini untuk mengintegrasikan dengan sertifikat software, key vault berbasis cloud, atau hardware security module (HSM).

Method

sign(string $data): string

Tanda tangani data yang diberikan dan kembalikan byte tanda tangan CMS/CAdES mentah.

certificate(): string

Kembalikan sertifikat penandatangan yang di-encode DER.

chain(): array

Kembalikan array sertifikat intermediate yang di-encode DER (dari penandatangan ke root).

estimatedSize(): int

Kembalikan estimasi ukuran maksimum (dalam byte) tanda tangan. Digunakan untuk pre-allocate placeholder ByteRange.

algorithm(): string

Kembalikan OID atau nama algoritma penandatangan (misalnya, 'sha256WithRSAEncryption').

Contoh

use TcpdfNext\Contracts\SignerInterface;

class FileSigner implements SignerInterface
{
    public function __construct(
        private readonly string $certPath,
        private readonly string $keyPath,
        private readonly string $password,
    ) {}

    public function sign(string $data): string
    {
        $cert = file_get_contents($this->certPath);
        $key = openssl_pkey_get_private(
            file_get_contents($this->keyPath),
            $this->password,
        );
        openssl_pkcs7_sign(/* ... */);
        // Kembalikan byte tanda tangan mentah
    }

    public function certificate(): string { /* ... */ }
    public function chain(): array { return []; }
    public function estimatedSize(): int { return 8192; }
    public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}

---

HsmSignerInterface

Namespace: TcpdfNext\Contracts\HsmSignerInterface

Meng-extend SignerInterface untuk hardware security module yang tidak pernah mengekspos private key. Alih-alih menandatangani data mentah, HSM menandatangani digest yang sudah dihitung sebelumnya.

Method

Semua method dari SignerInterface, ditambah:

signDigest(string $digest, string $algorithm): string

Tanda tangani message digest yang sudah dihitung sebelumnya. Parameter algorithm mengidentifikasi hash yang digunakan (misalnya, 'sha256').

Contoh

use TcpdfNext\Contracts\HsmSignerInterface;

class AwsCloudHsmSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly string $keyId,
        private readonly AwsKmsClient $kms,
        private readonly string $certPem,
    ) {}

    public function sign(string $data): string
    {
        $digest = hash('sha256', $data, binary: true);
        return $this->signDigest($digest, 'sha256');
    }

    public function signDigest(string $digest, string $algorithm): string
    {
        $result = $this->kms->sign([
            'KeyId' => $this->keyId,
            'Message' => $digest,
            'MessageType' => 'DIGEST',
            'SigningAlgorithm' => 'RSASSA_PKCS1_V1_5_SHA_256',
        ]);
        return $result['Signature'];
    }

    public function certificate(): string { return $this->certPem; }
    public function chain(): array { return []; }
    public function estimatedSize(): int { return 16384; }
    public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}

---

Menggunakan Interface untuk Testing

Keempat interface dirancang agar mudah di-mock dengan PHPUnit atau Mockery.

use PHPUnit\Framework\TestCase;
use TcpdfNext\Contracts\FontManagerInterface;

class TextRendererTest extends TestCase
{
    public function testCalculatesWidth(): void
    {
        $fonts = $this->createMock(FontManagerInterface::class);
        $fonts->method('hasFont')->willReturn(true);
        $fonts->method('stringWidth')
            ->with('Hello', 'Helvetica', 12.0, '')
            ->willReturn(26.64);

        $renderer = new TextRenderer($fonts);
        $this->assertEqualsWithDelta(26.64, $renderer->width('Hello'), 0.01);
    }
}

---

Lihat Juga

• Ringkasan API -- Semua paket sekilas
• Referensi Enum -- Enum yang digunakan oleh interface ini (Orientation, Alignment, OutputDestination)
• API Document -- Class konkret yang mengimplementasikan PdfDocumentInterface
• Panduan Keamanan -- Panduan lengkap enkripsi dan tanda tangan digital