NextPDF tasarım felsefesi

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

Bir bakışta

Bu sayfa, her NextPDF API kararının değerlendirildiği ilkeleri ortaya koyar. İlkeler bilinçli olarak az sayıdadır, çünkü ezberden söyleyemediğiniz bir ilkeyi baskı altında uygulayamazsınız.

Okunması gereken ilk sayfa budur. Diğer Insider_ sayfaları bu ilkeleri belirli yerlerde iş başında gösterir. Bu sayfa ise geri kalanının anlam kazanması için onları adlandırır.

Bunun neden önemli olduğu

PDF, ilke sahibi olacak kadar köklü ve tahminleri cezalandıracak kadar katıdır. Bir imza, tam olarak hangi baytları kapsıyorsa yalnızca onları kapsar. Bir yazı tipi ya gömülüdür ya da değildir. Bir arşivleme profili de aylar sonra kanıta ihtiyaç duyan birinin yaptığı denetimde ya geçerliliğini korur ya da başarısız olur.

Girdiler belirsiz olduğunda bir kitaplığın yapacağı bir seçim vardır. Tahmin yürütüp sessiz kalabilir ya da durup bunu açıkça söyleyebilir. İlki bir tanıtımda daha cana yakın görünür. Aynı zamanda, neyin yanlış gittiğine dair hiçbir iz bırakmayan bir üretim olayına da yol açabilir. NextPDF ikincisini seçer. Savunulabilir bir iz bırakmak karşılığında, daha az güven veren bir ilk izlenimi kabul eder. Yazılım kalitesi standartları bu takası doğrudan adlandırır. Fail-safe davranışı, bir ürünün hata durumunda tanımsız biçimde devam etmek yerine güvenli bir duruma dönme yeteneğidir ( Spec Spec: ISO/IEC 25010, §3 ISO/IEC 25010 §3 ).

Kısa özet

NextPDF, öncelik sırasına göre beş ilke üzerine kuruludur:

1. Açık olan, örtük olana üstündür. Niyet önemliyse, onu açıkça belirtirsiniz. Motor; bir imza düzeyini, bir çıktı modunu veya bir uygunluk hedefini bağlamdan çıkarsamaz.
2. Hızlı başarısız ol, açıkça başarısız ol, erken başarısız ol. Geçersiz bir girdi, tek bir bayt yazılmadan önce, nedenini adlandıran bir iletiyle reddedilir.
3. Hatalar bir API yüzeyidir. Hatalar özgüldür, türlendirilmiştir ve yapılandırılmış bağlam taşır — rastlantısal değil, tasarlanmıştır.
4. Sınırlar keşfedilmez, açıkça belirtilir. Her iddia nerede durduğunu söyler. “Gerekli, ama yeterli değil”, NextPDF’in bilinçli olarak kullandığı bir ifadedir.
5. Hiçbir şey sessizce bozulmaz. Motor, tamamlanmış gibi görünen yarı doğru bir çıktı döndürmez.

Geri kalan her şey — akıcı oluşturucu, tek kullanımlık belge, katı tipleme — bunların bir sonucudur.

NextPDF buna nasıl yaklaşır

İlkeler birer slogan değildir. Kaynak kodda somut biçimlere dönüşürler ve birbirlerini pekiştirirler.

Aşağıdaki tablo, her ilkeyi motorda nerede görebileceğiniz ve yokluğunun neye mal olacağıyla eşleştirir.

İlke	NextPDF’te nasıl ortaya çıkar	Tersinin maliyeti
Açık olan, örtük olana üstündür	setSignature(certInfo:, level:), PAdES düzeyini zorunlu ve adlandırılmış bir bağımsız değişken olarak alır — “otomatik” bir düzey yoktur	Yükümlülüğün gerektirmediği bir profille imzalanmış ve ancak doğrulama anında fark edilen bir belge
Hızlı başarısız ol, açıkça başarısız ol	save(), işlemeden önce bir akış sarmalayıcıyı veya null-bayt içeren bir yolu reddeder; setSignature() ardından save() çağrıldığında, imzasız bir dosya üretmek yerine bir istisna fırlatır	Bir yol geçişi (path-traversal) yazma işlemi ya da bir arşivde “imzasız olduğu hâlde imzalı sanılan” bir PDF
Hatalar bir API yüzeyidir	Tek bir soyut temel istisna ve özgül, türlendirilmiş alt sınıflar; her biri günlükler ve APM için yapılandırılmış getContext() sunar	Genel bir yığın izi ve tahminlerle geçen uzun bir öğleden sonra
Sınırlar açıkça belirtilir	Süreç içi uygunluk denetimleri bulgular döndürür ve nihai kararın bağımsız bir doğrulayıcıya ait olduğunu açıkça ifade eder	Bir denetçinin çürüttüğü “istisna yok, öyleyse uygun olmalı” çıkarımı
Hiçbir şey sessizce bozulmaz	Arşivleme zaman damgası yolu, gerekli sözlüğü eksik olan bir profil üretmek yerine yarım yazılmış bir profil döndürmeyi reddeder	Uzun vadeli doğrulama profili sanılan, ama sessizce öyle olmayan bir profil

İlkeleri bir arada okuyun, ortaya tek bir duruş çıkar: motor, size kendinden emin bir “belki” yerine dürüst bir “hayır” vermeyi yeğler. Bu kötümserlik değildir. Bu, PDF’in çoğu zaman hukuki bir belge olduğunu kabul etmektir. Yanlış olan bir hukuki belge, hiç üretilmemiş olandan daha kötüdür.

Human-factors note: Human-factors note

Sınırın, aracı benimsemenizden sonra değil önce belirtilmesinin insan faktörlerine dayanan bir nedeni vardır. Bir okur, bir ürünün ihtiyacına uygun olup olmadığını yalnızca ona bağlandıktan sonra değil, ilk izlenimlerden ve belgelerinden de anlayabilmelidir ( Spec Spec: ISO/IEC 25010, §3.26 ISO/IEC 25010 §3.26 ). Bu sayfa dahil her Insider_ sayfasının ne olduğunu söyleyerek başlayıp nerede durduğunu belirterek bitmesinin ve şu konuya ayrı bir sayfa ayrılmış olmasının nedeni budur: NextPDF ne zaman kullanılmamalı. Sınırı size erkenden söylemek nezakettir, zayıflık değil.

Kanıtlar ne söylüyor

Bu sayfa Evidence ◇ Design principle Evidence: Design principle niteliğindedir: ilkeler ölçülerek değil, gerekçelendirilerek ortaya konan bilinçli kararlardır. Bir ilkenin başka bir disiplinde karşılığı olduğunda, gerekçelendirme yalnızca şirket içi bir görüş olarak kalmasın diye sayfa ona dayanır.

• “Tanımsız bir durumda devam etmek yerine reddet” duruşu, fail-safe kalite özelliğidir; bu özellik Spec Spec: ISO/IEC 25010 ISO/IEC 25010 §3’te, hata durumunda kendini güvenli bir koşula yerleştiren ürün davranışı olarak tanımlanır. Aynı aileden olan fault tolerance (hata toleransı), bir sistemin hatalara rağmen amaçlandığı gibi davranmayı sürdürme derecesidir. NextPDF bu çabayı hatayı gizlemeye değil, onu saptamaya ve durdurmaya yöneltir.
• “Sınırı benimsemeden önce belirt” duruşu appropriateness recognizability (uygunluğun fark edilebilirliği) özelliğidir ( Spec Spec: ISO/IEC 25010, §3.26 ISO/IEC 25010 §3.26 ): belgelerden ve ilk izlenimlerden uygunluğa karar verebilme yeteneği.
• Bütün bunların PDF’e özgü olarak önemli olmasının nedeni Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 : bir imzanın bayt aralığı tam olarak kapsadığı baytları korur, fazlasını değil; dolayısıyla imzalı bir belgeyi “yardımcı olmak için” yeniden yazan veya onun çevresinde tahmin yürüten bir motor aslında hiç yardımcı olmamıştır.

Tek tek ilkeler, kendi sayfalarında gerçek motor kaynak kodu üzerinde gösterilir — Tahmin yürütmeyi reddeden bir API ve Bir özellik olarak hatalar sayfaları Evidence { } Code-backed Evidence: Code-backed kanıtını taşır. Bu sayfa nedenleri anlatır; o sayfalar ise bunun nasıl uygulandığını gösterir.

Uygulamalı örnek

İlkeler, sıradan kullanımın birkaç satırında görülebilir. İmza çağrısı, niyeti açıkça belirtir. Motor, yanıltıcı bir şey üretmek yerine erkenden reddeder.

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

Asıl mesele imza mekaniği değildir. Tek bir kod parçasında üç ilke gözlemlenebilir: niyet açıkça belirtilir (level:), hata erken ve adı konarak bildirilir ve motor, kendi durumu hakkında yalan söyleyecek bir belge üretmeyi reddeder.

Yaygın yanlış anlama

En yaygın yanlış yorum, bu ilkelerin NextPDF’i “kullanımı daha zor” hâle getirdiğidir. Bu ilkeler onu yanlış kullanmayı zorlaştırır. Zorunlu bir bağımsız değişken, sizi şaşırtacak sessiz bir varsayılanın ortadan kalkması demektir. Erken bir istisna, arşivde bir bozuk çıktı daha az demektir. Sürtünme, bilinçli olarak bir hatanın pahalı olduğu yere — üretimde, bir denetimde, mahkemede — değil, ucuz olduğu yere — çağrı noktasında, geliştirme sırasında — yerleştirilir.

İkinci yanlış yorum, “ilkeli olmak”ın “esnek olmamak” anlamına geldiğidir. Öyle değildir. Motorun, belgeniz hakkında değil, doğruluk ve niyet hakkında görüşleri vardır. Yerleşimi, içeriği, yazı tiplerini ve yapıyı yine de tamamen siz denetlersiniz. Bu görüşler, bir tahminin güvensiz olacağı yerde sizin adınıza tahmin yürütmemekle ilgilidir.

Limitler ve sınırlar

Bu sayfa tasarım niyetini ortaya koyar. Kendisi bir davranış belirtimi değildir. İlkeler, kararların nasıl alındığını tanımlar; herhangi bir yöntem hakkında bir garanti değildir. Her yöntemin tam sözleşmesi başvuru kılavuzunda ve o sayfanın kanıt düzeyiyle birlikte kendi Insider_ sayfasında yer alır.

İlkeler aynı zamanda mutlak fizik yasaları da değildir. Bunlar, muhakemeyle uygulanan önceliklerdir. İki ilke çeliştiğinde (daha katı bir reddetmeye karşı daha hoşgörülü bir varsayılan), yukarıdaki öncelik sırası belirleyici olur. Belirli bir modül yine de gerekçeli bir istisnayı belgeleyebilir. Belgelediğinde, o istisna varsayılmaz, yazılı olarak ortaya konur.

Son olarak, burada “tasarım ilkesi” bilinçli olarak kanıt düzeyidir. Bu sayfa gerekçelendirir. Karşılaştırmalı ölçüm sunmaz. Desteklenmesi için bir sayıya, bir teste veya bir maddeye ihtiyaç duyan iddialar burada değil, o kanıta sahip olan sayfalarda yapılır.

İlgili belgeler

• Tahmin yürütmeyi reddeden bir API — açık niyet ve hızlı başarısızlık ilkeleri, gerçek API üzerinde gösterilir.
• Bir özellik olarak hatalar — tasarlanmış bir yüzey olarak türlendirilmiş istisna hiyerarşisi.
• PHP 8.4 temelleri — bu ilkelerin umut edilmek yerine zorunlu kılınmasını sağlayan dil özellikleri.

Sözlük

• Tasarım ilkesi (kanıt düzeyi) — iddiaları, karşılaştırmalı bir ölçümle veya tek bir testle ölçülmek yerine niyetten ve destekleyici standartlardan gerekçelendirilen bilinçli tasarım kararlarına dayanan bir sayfa.
• Fail-safe — bir yazılım kalitesi özelliği: hata durumunda ürün, tanımsız bir durumda devam etmek yerine güvenli bir duruma döner. NextPDF’in tahmin yürütmek yerine reddetmesinin nedeni.
• Hızlı başarısızlık — geçersiz bir girdiyi, devam edip daha sonra belirsiz bir biçimde başarısız olmak yerine, mümkün olan en erken noktada açık bir nedenle reddetmek.
• PAdES — PDF Advanced Electronic Signatures, PDF belgelerini imzalamaya yönelik ETSI profil ailesi (B-B, B-T, B-LT, B-LTA). Burada ilk kullanımda açımlanmıştır; imzalama sayfalarında ayrıntılı olarak ele alınır.
• Gerekli, ama yeterli değil — süreç içi bir denetim gerçek bir işaret olduğunda ama bir uygunluk kararı olmadığında kullanılan bilinçli bir ifade; yetkili karar bağımsız bir doğrulayıcıya aittir.