Lewati ke konten
NextPDF

Contracts / Document

Sekilas pandang

Bagian berjudul “Sekilas pandang”

Domain dokumen berisi kontrak yang Anda gunakan untuk membangun keluaran Portable Document Format (PDF): PdfDocumentInterface untuk konten, DocumentFactoryInterface untuk pembuatan yang aman bagi worker, kontrak untuk registri fon dan gambar, serta tiga enum untuk pengiriman dan tata letak. Semuanya stable sejak 1.0.0 atau 1.7.0.

Instalasi

Bagian berjudul “Instalasi”
Terminal window
composer require nextpdf/core:^3

Gambaran konseptual

Bagian berjudul “Gambaran konseptual”

PdfDocumentInterface adalah permukaan utama application programming interface (API). Antarmuka ini mendefinisikan pengelolaan halaman, pemilihan fon, tata letak teks cell dan multi-cell, rendering Hypertext Markup Language (HTML), penyematan gambar, dan keluaran akhir. Setiap metode mengembalikan static, sehingga Anda dapat merangkai panggilan. Document::createStandalone() mengembalikan instance konkret yang memenuhi antarmuka tersebut. Gunakan type-hint ke antarmuka ini pada layanan Anda sendiri agar internal mesin tetap dapat ditukar.

Pembuatan dokumen memiliki dua jalur. Pada permintaan PHP FastCGI Process Manager (PHP-FPM) klasik, createStandalone() membangun dokumen mandiri dengan registri privat. Worker yang berjalan lama, termasuk RoadRunner, Swoole, dan Laravel Octane, menggunakan jalur lain. Dalam konteks itu, DocumentFactoryInterface::create() mengembalikan Document baru yang sekali pakai. Dokumen membaca dari registri yang bertahan selama proses berlangsung, tetapi tidak pernah mengubahnya. Factory menyimpan singleton FontRegistryInterface dan ImageRegistryInterface. Setiap dokumen mendapatkan konteks renderer dan writer-nya sendiri. Ini membatasi dampak kegagalan: satu dokumen tidak dapat merusak status bersama yang diandalkan dokumen lain.

Kontrak registri menjaga worker tetap cepat. FontRegistryInterface mengurai berkas fon satu kali dan menyimpan metadata hasil penguraian di cache selama proses berlangsung. Anda dapat menguncinya setelah warmup agar lalu lintas produksi tidak dapat mengubahnya. ImageRegistryInterface menyimpan data biner gambar yang sudah didekode dalam cache dengan kebijakan least-recently-used yang dibatasi. Metadata gambar tetap berada di memori bahkan setelah data binernya dikeluarkan. Kedua registri mengekspos memoryUsage() untuk perencanaan kapasitas. ImageRegistryInterface memperluas ResettableService, yang mengeluarkan data dari cache tanpa menghancurkan metadata struktural. Worker dapat membuang cache gambar saat memori tertekan dan tetap melayani permintaan.

Tiga enum melengkapi domain ini. OutputDestination memilih tampilan inline, unduhan paksa, penulisan ke filesystem, atau pengembalian string mentah. Orientation memilih portrait atau landscape. Alignment memilih teks rata kiri, tengah, kanan, atau rata kiri-kanan. Setiap enum menggunakan kode TCPDF lama sebagai nilai enum-nya, sehingga jembatan compat-tcpdf memetakannya dengan rapi. Janji kompatibilitas mundur untuk enum-enum ini bersifat aditif. Tidak ada case yang dihapus. Case baru dapat hadir dalam rilis minor.

Permukaan API

Bagian berjudul “Permukaan API”
TipeJenisAnggota utamaStabilitasSejak
PdfDocumentInterfaceinterfaceaddPage(), setMargins(), setFont(), cell(), multiCell(), writeHtml(), image(), output(), save()stabil1.0.0
DocumentFactoryInterfaceinterfacecreate(?Config): Documentstabil1.7.0
ResettableServiceinterfacereset(): voidstabil1.7.0
FontRegistryInterfaceinterfaceregister(), get(), warmup(), lock(), isLocked(), registerFromBinary(), memoryUsage()stabil1.7.0
ImageRegistryInterfaceinterfaceload(), loadFromString(), getMetadata(), memoryUsage() (memperluas ResettableService)stabil2.0.0
OutputDestinationenum (string)Inline, Download, File, Stringstabil1.0.0
Orientationenum (string)Portrait, Landscapestabil1.0.0
Alignmentenum (string)Left, Center, Right, Justifystabil1.0.0

Halaman tipografi mendokumentasikan FontRegistryInterface dan ImageRegistryInterface secara lengkap. Halaman ini membahas peran keduanya dalam siklus hidup pembuatan dokumen.

Contoh kode — Mulai cepat

Bagian berjudul “Contoh kode — Mulai cepat”
examples/01-hello-world.php
<?php


declare(strict_types=1);


require_once __DIR__ . '/../vendor/autoload.php';


use NextPDF\Core\Document;


$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This is a minimal PDF generated with NextPDF.', newLine: true);
$doc->save(__DIR__ . '/output/01-hello-world.pdf');

Contoh kode — Produksi

Bagian berjudul “Contoh kode — Produksi”
examples/02-pdf-factory.php
<?php


declare(strict_types=1);


require_once __DIR__ . '/../vendor/autoload.php';


use NextPDF\Core\PdfFactory;
use NextPDF\ValueObjects\{Margin, PageSize};


$factory = PdfFactory::new()
    ->withPageSize(PageSize::A4())
    ->withMargins(new Margin(15.0, 15.0, 15.0, 15.0))
    ->withCompress(true)
    ->withLang('en');


// The same configured factory creates independent documents.
$doc = $factory->create();
$doc->setTitle('PdfFactory Example');
$doc->setAuthor('NextPDF');
$doc->addPage();
$doc->setFont('helvetica', '', 16);
$doc->cell(0, 12, 'Created via PdfFactory', newLine: true);


$doc2 = $factory->create();
$doc2->addPage();
$doc2->setFont('helvetica', '', 12);
$doc2->cell(0, 10, 'Second document from the same factory.');


$doc->save(__DIR__ . '/output/02-pdf-factory.pdf');

PdfFactory adalah builder yang bersifat immutable. Setiap panggilan with*() mengembalikan instance baru. Di balik layar, builder ini merakit sebuah DocumentFactoryInterface, sehingga model registri worker dari gambaran umum berlaku tanpa wiring tambahan.

Kasus tepi & jebakan

Bagian berjudul “Kasus tepi & jebakan”
  • createStandalone() membangun registri privat. Dalam loop worker, hal itu mengurai ulang setiap fon pada setiap permintaan. Gunakan DocumentFactoryInterface dengan registri bersama sebagai gantinya.
  • Sebuah Document dirancang untuk sekali pakai. Menggunakan ulang satu instance untuk beberapa dokumen logis akan membocorkan status. Panggil create() untuk setiap dokumen dan biarkan garbage collection membersihkannya.
  • FontRegistryInterface::lock() membuat register(), addFontDirectory(), dan warmup() melempar LogicException. Lakukan penguncian setelah warmup, jangan pernah selama penanganan permintaan.
  • OutputDestination::File menulis ke filesystem server dan mengembalikan byte mentah. save() adalah jalur berkas eksplisit. Jangan mencampur keduanya untuk dokumen yang sama.
  • cell() menerima bool|string untuk argumen border demi kompatibilitas TCPDF. String kosong tidak sama dengan false. Berikan nilai dengan tipe yang sesuai maksud Anda.

Performa

Bagian berjudul “Performa”

Registri fon dan gambar menjadikan domain dokumen sebagai sistem yang dibatasi memori, bukan sistem per permintaan. Penguraian fon pada permintaan pertama menjadi faktor dominan. Nilai performance_budget adalah 1500 ms wall dan puncak 64 MB untuk tiga dokumen dalam contoh worker. Hampir seluruh anggaran itu berasal dari penguraian fon pertama. Setelah warmup, beban kerja per dokumen yang terkait dengan kontrak bersifat O(1): satu pencarian registri dan satu alokasi konteks. memoryUsage() pada salah satu registri mengembalikan sebuah MemoryReport untuk perencanaan kapasitas secara langsung. ResettableService::reset() membatasi memori puncak di bawah beban berkelanjutan.

Catatan keamanan

Bagian berjudul “Catatan keamanan”

Kontrak dokumen tidak memiliki permukaan kriptografis, tetapi ada dua risiko operasional. Pertama, image() menerima path atau Uniform Resource Locator (URL). Dalam skenario masukan tepercaya, batasi pengambilan jarak jauh melalui ExternalResourcePolicyInterface (lihat halaman security-policy), alih-alih meneruskan URL yang dikendalikan pengguna secara langsung. Kedua, writeHtml() adalah titik masuk untuk pipeline HTML. Markup tepercaya harus melewati HtmlSecurityPolicyInterface sebelum dirender. Lapisan dokumen sendiri tidak melakukan sanitasi. Itu adalah tugas domain security-policy, dan karena ini adalah kontrak, Anda dapat menyediakan kebijakan yang lebih ketat tanpa melakukan fork.

Konformitas

Bagian berjudul “Konformitas”

Kontrak dokumen mengimplementasikan struktur dokumen PDF 2.0 sebagaimana didefinisikan dalam ISO 32000-2. Penanganan keluaran, halaman, dan fon menghasilkan objek tak langsung dan stream cross-reference sesuai ISO 32000-2 §7. Lapisan writer memancarkan konten sesuai kontrak lapisan mesin, architecture decision record (ADR-010). Halaman ini tidak menyatakan klaim setingkat klausul di luar konformitas struktural. Halaman ekstraksi dan aksesibilitas mendokumentasikan konformitas PDF/A dan PDF/UA serta memuat tabel normatifnya.

Lihat juga

Bagian berjudul “Lihat juga”