Filosofi desain NextPDF

Spec: ISO/IEC 25010 Spec: ISO 32000-2 Evidence: Design principle

Sekilas pandang

Halaman ini menjabarkan prinsip-prinsip yang menjadi acuan setiap keputusan API NextPDF. Jumlahnya sengaja dibatasi, karena prinsip yang tidak dapat Anda hafalkan adalah prinsip yang tidak dapat Anda terapkan saat berada di bawah tekanan.

Inilah halaman yang sebaiknya Anda baca pertama kali. Halaman Insider_ lainnya menunjukkan bagaimana prinsip-prinsip ini bekerja di tempat-tempat tertentu. Halaman inilah yang memberi nama pada prinsip-prinsip itu agar halaman lainnya masuk akal.

Mengapa ini penting

PDF sudah cukup matang untuk memiliki pendirian, dan cukup ketat untuk menghukum tebakan. Sebuah tanda tangan mencakup tepat byte yang dicakupnya. Font itu tertanam atau tidak. Profil pengarsipan itu lolos atau gagal dalam audit beberapa bulan kemudian, di hadapan seseorang yang membutuhkan bukti.

Saat masukannya ambigu, sebuah pustaka memiliki pilihan. Pustaka itu dapat menebak dalam diam, atau berhenti dan menyatakannya. Pilihan pertama terasa lebih ramah dalam demo. Pilihan itu juga dapat menyebabkan insiden produksi tanpa jejak yang menjelaskan apa yang salah. NextPDF memilih yang kedua. NextPDF rela memberi kesan pertama yang kurang menenangkan demi perilaku yang dapat dipertanggungjawabkan. Standar kualitas perangkat lunak menyebut pertukaran ini secara langsung. Perilaku fail-safe adalah kemampuan produk untuk kembali ke keadaan aman saat terjadi kegagalan alih-alih melanjutkan dalam keadaan yang tidak terdefinisi ( Spec: ISO/IEC 25010, §3 ).

Versi singkat

NextPDF dibangun di atas lima prinsip, dalam urutan prioritas:

Eksplisit mengalahkan implisit. Jika niat penting, Anda menyatakannya. Mesin ini tidak menyimpulkan level tanda tangan, mode keluaran, atau target kesesuaian dari konteks.
Gagal cepat, gagal dengan jelas, gagal sedini mungkin. Masukan yang tidak valid ditolak sebelum satu byte pun ditulis, dengan pesan yang menyebutkan penyebabnya.
Galat adalah bagian dari permukaan API. Kegagalan bersifat spesifik, bertipe, dan membawa konteks terstruktur — dirancang, bukan terjadi secara kebetulan.
Batasan dinyatakan, bukan ditemukan sendiri. Setiap klaim menyatakan batas akhirnya. “Perlu, tetapi tidak cukup” adalah ungkapan yang sengaja digunakan NextPDF.
Tidak ada degradasi diam-diam. Mesin ini tidak mengembalikan artefak setengah benar yang tampak sudah selesai.

Semua hal lain — fluent builder, dokumen sekali pakai, pengetikan ketat — merupakan turunan dari prinsip-prinsip ini.

Bagaimana NextPDF menyikapinya

Prinsip-prinsip ini bukan slogan. Prinsip-prinsip ini muncul dalam bentuk konkret di kode sumber, dan saling memperkuat.

Tabel di bawah ini memetakan setiap prinsip ke tempat Anda dapat melihatnya di dalam mesin, beserta kerugiannya jika prinsip itu tidak ada.

Prinsip	Bagaimana ia muncul di NextPDF	Kerugian jika sebaliknya
Eksplisit mengalahkan implisit	`setSignature(certInfo:, level:)` menerima level PAdES sebagai argumen bernama yang wajib — tidak ada level “auto”	Dokumen ditandatangani pada profil yang sebenarnya tidak diwajibkan, dan baru diketahui saat validasi
Gagal cepat, gagal dengan jelas	`save()` menolak jalur stream-wrapper atau jalur dengan null-byte sebelum proses render; `setSignature()` yang diikuti oleh `save()` melempar pengecualian alih-alih menghasilkan berkas yang tidak ditandatangani	Penulisan path-traversal, atau PDF yang “tidak ditandatangani tetapi diyakini sudah ditandatangani” di dalam arsip
Galat adalah bagian dari permukaan API	Satu pengecualian dasar abstrak, subkelas bertipe spesifik, masing-masing memaparkan `getContext()` terstruktur untuk log dan APM	Jejak tumpukan yang generik dan sore panjang penuh tebakan
Batasan dinyatakan	Pemeriksaan kesesuaian dalam proses mengembalikan temuan dan menyatakan secara tegas bahwa putusan akhir adalah milik validator independen	Kesimpulan “tidak ada pengecualian, jadi pasti sudah sesuai” yang justru dibantah oleh auditor
Tidak ada degradasi diam-diam	Jalur archival-timestamp menolak mengembalikan profil yang baru ditulis setengah jalan alih-alih menghasilkan profil yang kehilangan kamus wajibnya	Profil long-term-validation yang diam-diam ternyata bukan profil semacam itu

Dibaca bersama-sama, prinsip-prinsip ini menunjukkan satu pendirian: mesin ini lebih memilih memberi Anda “tidak” yang jujur daripada “mungkin” yang penuh percaya diri. Itu bukan pesimisme. Ini adalah pengakuan bahwa sebuah PDF sering kali merupakan artefak hukum. Artefak hukum yang salah lebih buruk daripada artefak yang tidak pernah dibuat sama sekali.

Apa kata buktinya

Halaman ini merupakan pernyataan Evidence: Design principle : prinsip-prinsipnya adalah keputusan yang disengaja, didukung oleh argumen, bukan pengukuran. Apabila sebuah prinsip memiliki nama dalam disiplin eksternal, halaman ini mengaitkannya ke sana agar penalarannya bukan sekadar opini internal.

Pendirian “menolak alih-alih melanjutkan dalam keadaan yang tidak terdefinisi” adalah properti kualitas fail-safe dalam Spec: ISO/IEC 25010 §3 — produk yang menempatkan dirinya dalam kondisi aman saat terjadi kegagalan. Fault tolerance, dalam keluarga yang sama, adalah sejauh mana sebuah sistem tetap berperilaku sebagaimana seharusnya meski terjadi kesalahan. NextPDF mengarahkan upaya itu pada deteksi dan penghentian, bukan pada penyembunyian kesalahan.
Pendirian “menyatakan batasan sebelum adopsi” adalah appropriateness recognizability ( Spec: ISO/IEC 25010, §3.26 ): kemampuan menilai kecocokan dari dokumentasi dan kesan pertama.
Alasan khusus PDF mengapa semua ini penting adalah Spec: ISO 32000-2, §12.8 : byte range sebuah tanda tangan melindungi persis byte yang dicakupnya dan tidak lebih, sehingga mesin yang “dengan niat membantu” menulis ulang atau menebak-nebak di seputar dokumen yang sudah ditandatangani sama sekali tidak membantu.

Setiap prinsip secara individual ditunjukkan dengan mengacu pada kode sumber mesin yang sesungguhnya di halamannya masing-masing — An API that refuses to guess dan Errors as a feature membawa Evidence: Code-backed buktinya. Halaman ini adalah mengapanya; halaman-halaman itu menunjukkan apanya.

Contoh praktis

Prinsip-prinsip ini terlihat dalam beberapa baris penggunaan biasa. Pemanggilan untuk tanda tangan menyatakan niat secara eksplisit. Mesin ini menolak sejak dini alih-alih menghasilkan sesuatu yang menyesatkan.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NotImplementedException;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

$document = Document::createStandalone();
$document->setTitle('Service Agreement 2026-0042');
$document->addPage();
$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This agreement is configured for a PAdES signature.', newLine: true);

// Explicit beats implicit: the PAdES level is a required, named argument.
// There is no inferred or "auto" level.
$document->setSignature(
    certInfo: new CertificateInfo(
        certificate: $certificatePem,
        privateKey: $privateKeyPem,
    ),
    level: SignatureLevel::PAdES_B_B,
);

try {
    // Fail fast, no silent degradation: rather than emit an UNSIGNED file
    // that the caller believes setSignature() signed, the high-level path
    // refuses and names the supported route.
    $document->save('/srv/output/agreement.pdf');
} catch (NotImplementedException $e) {
    // The message identifies the feature and the follow-up, not a stack
    // trace: "... is not implemented in this release. <actionable follow-up>"
    error_log($e->getMessage());
}

Intinya bukan mekanisme tanda tangannya. Tiga prinsip dapat diamati dalam satu cuplikan: niat dinyatakan (level:), kegagalan terjadi sejak dini dan penyebabnya disebutkan, serta mesin menolak menghasilkan dokumen yang akan berbohong tentang keadaannya sendiri.

Kesalahpahaman umum

Kesalahpahaman yang paling umum adalah bahwa prinsip-prinsip ini membuat NextPDF “lebih sulit digunakan”. Prinsip-prinsip ini membuatnya lebih sulit digunakan secara keliru. Argumen wajib berarti ada satu nilai bawaan diam-diam lebih sedikit yang bisa mengejutkan Anda. Pengecualian dini berarti ada satu artefak rusak lebih sedikit di dalam arsip. Friksi ini sengaja ditempatkan saat biaya kesalahan masih murah — di lokasi pemanggilan, saat pengembangan — alih-alih saat biaya kesalahan mahal: di produksi, dalam sebuah audit, di pengadilan.

Kesalahpahaman kedua adalah bahwa “memiliki pendirian” berarti “kaku”. Tidak demikian. Mesin ini memiliki pendirian tentang kebenaran dan niat, bukan tentang dokumen Anda. Anda tetap mengendalikan tata letak, konten, font, dan struktur sepenuhnya. Pendirian itu menyangkut penolakan untuk menebak atas nama Anda di tempat tebakan akan menjadi tidak aman.

Batas dan batasan

Halaman ini menyatakan niat desain. Halaman ini sendiri bukan spesifikasi perilaku. Prinsip-prinsip ini menggambarkan bagaimana keputusan diambil, bukan jaminan atas metode tertentu. Kontrak persis untuk setiap metode berada di dalam referensi dan di halaman Insider_-nya sendiri dengan tingkat bukti halaman tersebut.

Prinsip-prinsip ini juga bukan hukum fisika yang mutlak. Prinsip-prinsip ini adalah prioritas, yang diterapkan dengan pertimbangan. Apabila dua prinsip berbenturan (penolakan yang lebih ketat versus nilai bawaan yang lebih longgar), urutan prioritas di atas yang menentukan. Modul tertentu tetap dapat mendokumentasikan pengecualian yang beralasan. Apabila itu terjadi, pengecualian tersebut ditulis, bukan diasumsikan.

Terakhir, “prinsip desain” adalah basis bukti di sini secara sengaja. Halaman ini berargumen. Halaman ini tidak melakukan benchmark. Klaim yang perlu didukung angka, uji, atau klausul dibuat di halaman-halaman yang memiliki bukti tersebut, bukan di sini.

Dokumen terkait

An API that refuses to guess — prinsip niat-eksplisit dan gagal-cepat, ditunjukkan dengan mengacu pada API yang sesungguhnya.
Errors as a feature — hierarki pengecualian bertipe sebagai permukaan yang dirancang.
The PHP 8.4 foundations — fitur bahasa yang memungkinkan prinsip-prinsip ini ditegakkan alih-alih sekadar diharapkan.

Glosarium

Prinsip desain (tingkat bukti) — halaman yang klaimnya berupa keputusan desain yang disengaja, didasarkan pada niat dan standar yang menguatkan alih-alih diukur dengan benchmark atau satu uji tunggal.
Fail-safe — sebuah properti kualitas perangkat lunak: saat terjadi kegagalan, produk kembali ke keadaan aman alih-alih melanjutkan dalam keadaan yang tidak terdefinisi. Inilah alasan NextPDF menolak alih-alih menebak.
Fail fast — menolak masukan yang tidak valid pada titik sedini mungkin, dengan penyebab yang jelas, alih-alih melanjutkan dan gagal secara tidak jelas kemudian.
PAdES — PDF Advanced Electronic Signatures, keluarga profil ETSI untuk menandatangani dokumen PDF (B-B, B-T, B-LT, B-LTA). Dijabarkan di sini saat pertama kali digunakan; dibahas secara mendalam di halaman-halaman penandatanganan.
Perlu, tetapi tidak cukup — ungkapan yang sengaja digunakan ketika sebuah pemeriksaan dalam proses merupakan sinyal nyata tetapi bukan putusan kesesuaian; keputusan otoritatif adalah milik validator independen.