Filozofia projektowania NextPDF

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

W skrócie

Ta strona przedstawia zasady, według których weryfikowana jest każda decyzja dotycząca API NextPDF. Celowo jest ich niewiele, ponieważ zasadę, której nie da się przywołać z pamięci, trudno zastosować pod presją.

To strona, od której warto zacząć. Pozostałe strony Insider_ pokazują te zasady w działaniu w konkretnych miejscach. Ta nadaje im nazwy, dzięki czemu reszta nabiera sensu.

Dlaczego to ma znaczenie

PDF jest wystarczająco dojrzały, by mieć własne wymagania, i wystarczająco rygorystyczny, by karać za domysły. Podpis obejmuje dokładnie te bajty, które obejmuje. Czcionka jest albo osadzona, albo nie. Profil archiwizacyjny albo przechodzi audyt wiele miesięcy później, w obecności osoby oczekującej dowodów, albo go nie przechodzi.

Gdy dane wejściowe są niejednoznaczne, biblioteka staje przed wyborem. Może zgadywać i milczeć albo zatrzymać się i to zasygnalizować. Pierwsze rozwiązanie robi lepsze wrażenie podczas pokazu. Może też skończyć się awarią na produkcji bez żadnego śladu tego, co poszło nie tak. NextPDF wybiera drugie. Godzi się na mniej komfortowe pierwsze wrażenie w zamian za takie, które da się obronić. Standardy jakości oprogramowania nazywają ten kompromis wprost. Zachowanie fail-safe to zdolność produktu do powrotu do bezpiecznego stanu w razie awarii, zamiast kontynuowania w stanie niezdefiniowanym ( Spec Spec: ISO/IEC 25010, §3 ISO/IEC 25010 §3 ).

Wersja skrócona

NextPDF opiera się na pięciu zasadach, w kolejności priorytetów:

1. Jawne jest lepsze niż domyślne. Jeśli intencja ma znaczenie, deklarujesz ją. Silnik nie wnioskuje na podstawie kontekstu poziomu podpisu, trybu wyjściowego ani celu zgodności.
2. Zawódź szybko, zawódź głośno, zawódź wcześnie. Nieprawidłowe dane wejściowe są odrzucane, zanim zostanie zapisany choćby jeden bajt, wraz z komunikatem wskazującym przyczynę.
3. Błędy są częścią interfejsu API. Niepowodzenia są konkretne, typowane i zawierają ustrukturyzowany kontekst — zaprojektowane, a nie przypadkowe.
4. Granice są deklarowane, a nie odkrywane. Każde stwierdzenie wskazuje, gdzie kończy się jego zakres. „Konieczne, lecz niewystarczające” to sformułowanie, którego NextPDF używa celowo.
5. Nic nie ulega cichej degradacji. Silnik nie zwraca w połowie poprawnego artefaktu, który wygląda na ukończony.

Wszystko inne — płynny builder, jednorazowy dokument, ścisłe typowanie — jest pochodną tych zasad.

Jak podchodzi do tego NextPDF

Te zasady nie są sloganami. Przejawiają się jako konkretne rozwiązania w kodzie źródłowym i wzajemnie się wzmacniają.

Poniższa tabela przypisuje każdej zasadzie miejsce, w którym widać ją w silniku, oraz koszt jej braku.

Zasada	Jak przejawia się w NextPDF	Koszt przeciwieństwa
Jawne jest lepsze niż domyślne	setSignature(certInfo:, level:) przyjmuje poziom PAdES jako wymagany, nazwany argument — nie ma poziomu „auto”	Dokument podpisany profilem, którego dany obowiązek nie wymagał, wykryty dopiero podczas walidacji
Zawódź szybko, zawódź głośno	save() odrzuca ścieżkę z opakowaniem strumieniowym lub bajtem null przed renderowaniem; setSignature(), po którym następuje save(), zgłasza wyjątek, zamiast utworzyć niepodpisany plik	Zapis poza dozwoloną ścieżką (path traversal) albo plik PDF w archiwum „niepodpisany, lecz uznawany za podpisany”
Błędy są częścią interfejsu API	Jeden abstrakcyjny wyjątek bazowy, konkretne typowane podklasy, z których każda udostępnia ustrukturyzowany getContext() na potrzeby logów i APM	Ogólny ślad stosu i długie popołudnie zgadywania
Granice są deklarowane	Wewnątrzprocesowe kontrole zgodności zwracają ustalenia i wprost stwierdzają, że werdykt należy do niezależnego walidatora	Wniosek „brak wyjątku, więc musi być zgodne”, który audytor obala
Nic nie ulega cichej degradacji	Ścieżka znacznika czasu archiwizacji odmawia zwrócenia w połowie zapisanego profilu, zamiast utworzyć profil pozbawiony wymaganego słownika	Profil walidacji długoterminowej, który po cichu nim nie jest

Czytane łącznie, te zasady składają się na jedno stanowisko: silnik woli dać szczere „nie” niż pewne siebie „być może”. To nie pesymizm. To uznanie faktu, że PDF jest często artefaktem o znaczeniu prawnym. Błędny artefakt o znaczeniu prawnym jest gorszy niż taki, który nigdy nie powstał.

Human-factors note: Human-factors note

Istnieje powód z obszaru czynnika ludzkiego, dla którego granica jest deklarowana, zanim przyjmiesz to narzędzie, a nie po fakcie. Czytelnik powinien móc rozpoznać, czy produkt odpowiada jego potrzebom na podstawie pierwszego wrażenia i dokumentacji, a nie dopiero po zdecydowaniu się na niego ( Spec Spec: ISO/IEC 25010, §3.26 ISO/IEC 25010 §3.26 ). Właśnie dlatego każda strona Insider_ — w tym ta — zaczyna się od tego, czym jest, a kończy na tym, gdzie się kończy, i dlaczego istnieje cała strona poświęcona temu, kiedy nie używać NextPDF. Wskazanie ograniczeń z wyprzedzeniem to uprzejmość, a nie słabość.

Co mówią dowody

Ta strona ma charakter deklaracji typu Evidence ◇ Design principle Evidence: Design principle : zasady są świadomymi decyzjami, raczej uzasadnianymi argumentami niż mierzonymi. Tam, gdzie zasada ma nazwę w zewnętrznej dziedzinie, strona się do niej odwołuje, aby rozumowanie nie było wyłącznie opinią wewnętrzną.

• Stanowisko „odmów, zamiast kontynuować w niezdefiniowanym stanie” to właściwość jakościowa fail-safe z Spec Spec: ISO/IEC 25010 ISO/IEC 25010 §3 — produkt, który w razie awarii przechodzi w bezpieczny stan. Odporność na błędy (fault tolerance), z tej samej rodziny, to stopień, w jakim system zachowuje się zgodnie z zamierzeniem pomimo wystąpienia błędów. NextPDF koncentruje ten wysiłek na wykrywaniu i zatrzymywaniu, a nie na ukrywaniu błędu.
• Stanowisko „zadeklaruj granicę przed przyjęciem” to rozpoznawalność przydatności (appropriateness recognizability) ( Spec Spec: ISO/IEC 25010, §3.26 ISO/IEC 25010 §3.26 ): zdolność do oceny dopasowania na podstawie dokumentacji i pierwszego wrażenia.
• Specyficzny dla PDF powód, dla którego to wszystko ma znaczenie, to Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 : zakres bajtów podpisu chroni dokładnie te bajty, które obejmuje, i nic ponadto, więc silnik, który „pomocnie” przepisuje podpisany dokument lub opiera się na domysłach wokół niego, wcale nie pomógł.

Poszczególne zasady pokazano na rzeczywistym kodzie źródłowym silnika na ich własnych stronach — An API that refuses to guess oraz Errors as a feature zawierają Evidence { } Code-backed Evidence: Code-backed dowód. Ta strona to „dlaczego”; tamte strony to „co”.

Praktyczny przykład

Te zasady widać w kilku wierszach typowego użycia. Wywołanie podpisu deklaruje intencję wprost. Silnik odmawia wcześnie, zamiast utworzyć coś wprowadzającego w błąd.

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

Nie o mechanizm podpisu tu chodzi. W jednym fragmencie widać trzy zasady: intencja jest zadeklarowana (level:), niepowodzenie następuje wcześnie i jest nazwane, a silnik odmawia utworzenia dokumentu, który kłamałby na temat własnego stanu.

Częste nieporozumienie

Najczęstsze błędne odczytanie to przekonanie, że te zasady sprawiają, iż NextPDF jest „trudniejszy w użyciu”. Sprawiają, że trudniej używać go błędnie. Wymagany argument to o jedną cichą wartość domyślną mniej, która mogłaby zaskoczyć. Wczesny wyjątek to o jeden uszkodzony artefakt mniej w archiwum. Tarcie celowo pojawia się tam, gdzie błąd jest tani — w miejscu wywołania, na etapie tworzenia oprogramowania — a nie tam, gdzie jest kosztowny: na produkcji, podczas audytu, w sądzie.

Drugie błędne odczytanie to przekonanie, że „mający własne zdanie” oznacza „nieelastyczny”. Nie oznacza. Silnik ma zdanie na temat poprawności i intencji, a nie na temat Twojego dokumentu. Nadal masz pełną kontrolę nad układem, treścią, czcionkami i strukturą. To zdanie dotyczy tego, by nie zgadywać w Twoim imieniu tam, gdzie domysł byłby niebezpieczny.

Ograniczenia i granice

Ta strona przedstawia intencję projektową. Sama w sobie nie jest specyfikacją zachowania. Zasady opisują sposób podejmowania decyzji, a nie gwarancję dotyczącą jakiejkolwiek pojedynczej metody. Dokładny kontrakt każdej metody znajduje się w dokumentacji referencyjnej oraz na odpowiadającej jej stronie Insider_ wraz z przypisanym jej poziomem dowodów.

Te zasady nie są też absolutnymi prawami fizyki. Są priorytetami stosowanymi z rozwagą. Gdy dwie zasady są ze sobą w konflikcie (bardziej rygorystyczna odmowa kontra bardziej wyrozumiała wartość domyślna), o rozstrzygnięciu decyduje powyższa kolejność priorytetów. Konkretny moduł może mimo to udokumentować uzasadniony wyjątek. Gdy to robi, taki wyjątek jest opisany, a nie zakładany.

Wreszcie „zasada projektowa” jest tu z założenia podstawą dowodową. Ta strona przedstawia argumenty. Nie przeprowadza testów wydajności. Stwierdzenia, które wymagają liczby, testu lub klauzuli na poparcie, formułowane są na stronach zawierających takie dowody, a nie tutaj.

Powiązane dokumenty

• An API that refuses to guess — zasady jawnej intencji i szybkiego niepowodzenia, pokazane na rzeczywistym API.
• Errors as a feature — typowana hierarchia wyjątków jako zaprojektowany interfejs.
• The PHP 8.4 foundations — funkcje języka, które pozwalają egzekwować te zasady, a nie tylko mieć na nie nadzieję.

Słowniczek

• Zasada projektowa (poziom dowodów) — strona, której stwierdzenia są świadomymi decyzjami projektowymi, uzasadnianymi intencją i wspieranymi standardami, a nie mierzonymi testem wydajności czy pojedynczym testem.
• Fail-safe — właściwość jakościowa oprogramowania: w razie awarii produkt wraca do bezpiecznego stanu, zamiast kontynuować w stanie niezdefiniowanym. Powód, dla którego NextPDF odmawia, zamiast zgadywać.
• Fail fast — odrzucanie nieprawidłowych danych wejściowych w najwcześniejszym możliwym momencie, z jasną przyczyną, zamiast kontynuowania i niejednoznacznej awarii później.
• PAdES — PDF Advanced Electronic Signatures, rodzina profili ETSI do podpisywania dokumentów PDF (B-B, B-T, B-LT, B-LTA). Rozwinięte tutaj przy pierwszym użyciu; szczegółowo omówione na stronach dotyczących podpisywania.
• Konieczne, lecz niewystarczające — celowe sformułowanie używane, gdy wewnątrzprocesowa kontrola jest rzeczywistym sygnałem, lecz nie werdyktem zgodności; miarodajna decyzja należy do niezależnego walidatora.