Model pipeline

Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 Evidence { } Code-backed Evidence: Code-backed

Sekilas pandang

Dokumen NextPDF tidak dihasilkan dalam satu langkah tertutup. Dokumen tersebut melewati sejumlah kecil tahap eksplisit: sebuah fasad yang merekam maksud, lapisan konten yang mengubah maksud menjadi model, dan penulis yang menserialisasi model tersebut menjadi PDF yang patuh. Halaman ini menjelaskan bentuk tersebut dan mengapa bentuk itu tepat untuk mesin ini.

Mengapa ini penting

Format berkas PDF sendiri adalah struktur berlapis — sebuah header, badan berisi objek, tabel referensi-silang, dan trailer — dan penulis harus merakit semuanya secara konsisten. Jika mesin yang membangunnya berupa satu prosedur yang kusut, setiap perubahan dapat membahayakan setiap keluaran. Satu-satunya cara untuk memperoleh keyakinan kemudian adalah merender seluruh dokumen dan memeriksanya secara visual; proses ini lambat, terlambat, dan tidak meyakinkan.

Pipeline yang eksplisit membalikkan keadaan itu. Setiap tahap memiliki satu tugas dan batas bertipe, sehingga Anda dapat menalar sebuah perubahan dan mengujinya pada tahap yang disentuh, bukan hanya di akhir berkas. Arsitektur ini terutama merupakan keputusan tentang keterujian dan kemampuan untuk diperluas sebelum hal lain apa pun.

Versi singkatnya

• Titik masuk publiknya adalah sebuah fasad Document. Fasad ini adalah builder yang fluent, sekali pakai, dan aman bagi worker; ia merekam apa yang Anda inginkan, bukan bagaimana hal itu diserialisasi.
• Fasad ini mendelegasikan ke sekitar dua lusin concern trait yang terfokus (keluaran teks, penggambaran, halaman, keamanan, navigasi, dan seterusnya) — masing-masing satu tanggung jawab, bukan satu kelas raksasa.
• Konten tiba melalui salah satu dari dua jalur: penggambaran langsung (primitif grafis) atau mesin HTML/CSS. Keduanya menghasilkan model dokumen internal yang sama.
• Sebuah penulis PDF khusus menserialisasi model tersebut, memilih strategi PDF 1.4 / 1.7 / 2.0. Pembentukan struktur berkas yang valid berada di sini dan tidak di tempat lain.
• State berumur panjang (registri huruf dan gambar) berada dalam cakupan proses dan dibagikan; state per permintaan (dokumen) dibuat baru dan tidak pernah dipakai ulang. Batasnya eksplisit, dan inilah yang membuat runtime worker aman.

Bagaimana NextPDF menanganinya

Cara paling jelas untuk melihat model ini adalah mengikuti sebuah dokumen dari pemanggilan hingga menjadi byte.

1. Document facade Fluent, use-once builder; records intent via concern traits.
2. Content production Direct drawing or the HTML/CSS engine — both build one document model.
3. Document model Accumulated pages, content, and resources held as typed state.
4. PDF writer Serialises the model; selects a PDF 1.4 / 1.7 / 2.0 strategy.
5. Conforming PDF Header, object body, cross-reference table, trailer.

Jalur sebuah dokumen melewati NextPDF: setiap tahap memiliki satu tanggung jawab dan batas bertipe, sehingga dapat dinalar dan diuji secara terpisah.

Dua pilihan desain membuat hal ini lebih dari sekadar diagram.

Fasad ini tersusun dari banyak bagian, bukan monolitik. Document tidak mengimplementasikan setiap fitur sendiri; ia mendelegasikan setiap area ke concern trait khusus — keluaran teks, penggambaran, halaman, keamanan, tipografi, navigasi, transaksi, dan seterusnya. Metode dokumen baru ditempatkan pada trait yang menguasai areanya, bukan pada fasad itu sendiri. Kelas yang Anda panggil tetap kecil, dan tanggung jawab tetap terpisah.

Penulis menguasai struktur berkas secara eksklusif. Produksi konten menentukan apa saja mark dan objek yang ada; penulis menentukan bagaimana semuanya menjadi berkas PDF yang valid, termasuk strategi versi mana yang berlaku. Pemisahan itu ditegakkan sebagai aturan arsitektur: kode tata letak dan konten tidak memancarkan struktur berkas final, dan penulis tidak membuat keputusan tata letak. Manfaatnya adalah pertanyaan “apakah keluarannya merupakan PDF yang valid?” memiliki tepat satu tempat untuk diuji.

Batas masa hidup adalah bagian dari model, bukan sekadar pertimbangan belakangan. Registri huruf dan gambar bertahan sepanjang masa hidup proses dan dibagikan lintas permintaan; dokumen, konteks perenderannya, dan penulis dibuat per permintaan lalu dibuang. Dalam runtime worker, perbedaan itu menentukan apakah pemakaian ulang aman atau justru menimbulkan kerusakan lintas permintaan. Karena itu, batas ini dinyatakan dalam arsitektur, bukan diserahkan pada kedisiplinan.

Apa kata buktinya

Halaman ini bersifat Evidence { } Code-backed Evidence: Code-backed . Tahap-tahap tersebut dipetakan ke struktur nyata di repositori inti:

• Fasad dan delegasinya adalah src/Core/Document.php beserta concern trait di src/Core/Concerns/ (keluaran teks, output, penggambaran, halaman, keamanan, tipografi, navigasi, transaksi, dan lainnya — masing-masing satu tanggung jawab).
• Dua jalur konten tersebut adalah mesin HTML/CSS (src/Html/) dan penggambaran langsung (src/Graphics/), keduanya memasok model internal.
• Serialisasi dan strategi versi PDF berada di src/Writer/ (PdfWriter.php, dengan kelas strategi PDF 1.4 / 1.7 / 2.0 yang eksplisit).
• Batas antara masa-hidup-proses dan per-permintaan adalah desain aman-bagi-worker yang dicatat dalam ikhtisar arsitektur dan dipraktikkan oleh contoh worker-factory yang disertakan, yang berbagi satu FontRegistry dan ImageRegistry lintas permintaan sembari membuat setiap Document baru.

Tujuannya ditentukan oleh format. Keluaran penulis harus berupa header, badan objek, tabel referensi-silang, dan trailer sesuai Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 . Memusatkan kewajiban itu pada satu tahap itulah yang memungkinkan sisa mesin tetap berfokus pada konten alih-alih merakit struktur berkas.

Contoh praktis

Tugas fasad adalah membuat maksud terbaca seperti maksud itu sendiri. Jalur konten dan penulis tetap tak terlihat dari sisi pemanggilan:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();   // facade
$doc->setTitle('Quarterly Report');    // metadata concern
$doc->addPage();                       // pages concern
$doc->setFont('helvetica', 'B', 16);   // typography concern
$doc->cell(0, 12, 'Summary', newLine: true); // text-output concern
$doc->writeHtml('<p>Generated in-process.</p>'); // HTML content path
$doc->save(__DIR__ . '/report.pdf');   // writer stage

Setiap pemanggilan mendarat di concern yang berbeda. Dua jalur konten yang berbeda memasok model yang sama. Tepat satu tahap — save() — mengubah model menjadi byte berkas. Tidak ada apa pun di sisi pemanggilan yang perlu mengetahui cara tabel referensi-silang dibangun.

Kesalahpahaman umum

Salah tafsir yang sering muncul adalah bahwa “pipeline” mengimplikasikan API push streaming yang Anda rangkai tahap demi tahap, seperti pipe Unix. Tidak demikian. Pipeline di sini adalah dekomposisi arsitektural: tahap-tahap dengan tanggung jawab tunggal dan batas bertipe. Anda tetap memrogram terhadap fasad yang fluent. Tahap-tahap itu adalah cara mesin dibangun dan diuji, bukan transport yang Anda rakit dengan tangan.

Kesalahan terkait adalah menganggap fasad adalah mesinnya. Fasad adalah titik masuk. Pekerjaan sesungguhnya tersebar di antara concern trait, dua jalur konten, dan sebuah penulis. Distribusi inilah yang membuat satu perubahan fitur tidak membahayakan setiap keluaran.

Human-factors note: Human-factors note

Rangkaian lima tahap yang sama digunakan dalam diagram, versi singkat, bukti, dan contoh — secara sengaja. Struktur konsisten yang ditemui pembaca sekali lalu dikenali di mana-mana mengurangi upaya untuk mengikuti halaman ini. Ini mencerminkan alasan mesin itu sendiri menjaga batas tahap tetap dan sedikit, bukan banyak dan cair.

Batasan dan ruang lingkup

Halaman ini menjelaskan bentuk pipeline, bukan API internal dari tahap mana pun. Inventaris concern trait yang persis, aturan pemilihan strategi penulis, dan field model-konten ditentukan oleh kode dan referensi, bukan oleh penjelasan ini. Jumlah trait yang persis adalah detail implementasi yang dapat berubah tanpa mengubah model. Halaman ini tidak mencakup tahap-tahap internal mesin HTML (topik tersendiri) atau perilaku streaming dan memori penulis (juga tersendiri). Klaim struktural ini akurat per tanggal peninjauan halaman ini; sumber otoritatifnya adalah src/Core/, src/Html/, src/Graphics/, dan src/Writer/ di repositori inti.

Model pipeline ini identik di semua edisi; edisi menambahkan kapabilitas di dalam tahap, bukan tahap baru:

Pipeline model — edition availability

Edition	Availability
Core	○ Core mengimplementasikan alur pemrosesan lengkap fasad → konten → penulis.
Pro	○ Pro menambahkan kapabilitas di dalam tahap yang ada, bukan tahap baru.
Enterprise	○ Enterprise menambahkan kapabilitas di dalam tahap yang ada, bukan tahap baru.

Dokumen terkait

• Memori dan streaming — cara tahap penulis menjaga penggunaan memori tetap terbatas.
• Alur pemrosesan HTML — tahap-tahap internal jalur konten HTML.
• Tipe ketat, di mana-mana — batas bertipe yang membuat setiap tahap dapat diuji secara mandiri.

Glosarium

• Fasad — titik masuk publik Document: builder yang fluent dan sekali pakai yang merekam maksud serta mendelegasikan ke concern trait.
• Concern trait — trait PHP yang terfokus yang disusun oleh fasad, masing-masing menguasai satu area fitur (keluaran teks, penggambaran, halaman, keamanan, dan seterusnya).
• Jalur konten — salah satu dari dua cara konten masuk ke model: penggambaran langsung atau mesin HTML/CSS.
• Model dokumen — akumulasi internal mesin yang bertipe untuk halaman, konten, dan sumber daya sebelum serialisasi.
• Tahap penulis — komponen yang menserialisasi model menjadi PDF yang valid, memilih strategi PDF 1.4 / 1.7 / 2.0.
• Aman bagi worker — dirancang agar state berumur-proses dibagikan dengan aman sementara state per-permintaan dibuat baru dan tidak pernah dipakai ulang.