Die Designphilosophie von NextPDF

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

Auf einen Blick

Diese Seite benennt die Prinzipien, an denen jede NextPDF-API-Entscheidung gemessen wird. Es sind bewusst nur wenige, denn ein Prinzip, das Sie nicht aufsagen können, wenden Sie unter Druck auch nicht an.

Diese Seite sollten Sie zuerst lesen. Die anderen Insider_-Seiten zeigen, wie diese Prinzipien an konkreten Stellen wirken. Diese hier benennt sie, damit der Rest verständlich wird.

Warum das wichtig ist

PDF ist alt genug, um Überzeugungen zu haben, und streng genug, um Vermutungen zu bestrafen. Eine Signatur deckt exakt die Bytes ab, die sie abdeckt. Eine Schriftart ist entweder eingebettet oder nicht. Ein Archivierungsprofil hält entweder stand oder scheitert Monate später in einer Prüfung – vor jemandem, der darüber nicht amüsiert ist.

Bei mehrdeutigen Eingaben hat eine Bibliothek die Wahl: Sie kann raten und schweigen, oder sie kann anhalten und den Grund nennen. Die erste Variante wirkt in der Demo freundlicher. Sie kann Sie aber auch einen Produktionsvorfall kosten, ohne eine Spur davon zu hinterlassen, was schiefgelaufen ist. NextPDF entscheidet sich für die zweite Variante. Es nimmt einen weniger beruhigenden ersten Eindruck in Kauf, um dafür ein Ergebnis zu liefern, das vertretbar ist. Softwarequalitätsstandards benennen diesen Kompromiss direkt. Fail-safe-Verhalten ist die Fähigkeit eines Produkts, bei einem Fehler in einen sicheren Zustand zurückzukehren, statt in einem undefinierten Zustand weiterzulaufen ( Spec: ISO/IEC 25010, §3 ).

Die Kurzfassung

NextPDF beruht auf fünf Prinzipien, in der Reihenfolge ihrer Priorität:

Explizit schlägt implizit. Wenn die Absicht zählt, geben Sie sie an. Die Engine leitet weder eine Signaturstufe noch einen Ausgabemodus noch ein Konformitätsziel aus dem Kontext ab.
Schnell, laut und früh scheitern. Eine ungültige Eingabe wird abgelehnt, bevor ein Byte geschrieben wird, mit einer Meldung, die die Ursache benennt.
Fehler sind eine API-Oberfläche. Fehlschläge sind spezifisch, typisiert und tragen strukturierten Kontext – entworfen, nicht zufällig.
Grenzen werden benannt, nicht entdeckt. Jede Aussage macht klar, wo sie endet. „Notwendig, nicht hinreichend“ ist eine Formulierung, die NextPDF bewusst verwendet.
Nichts verschlechtert sich stillschweigend. Die Engine liefert kein halbkorrektes Artefakt aus, das fertig aussieht.

Alles andere – der Fluent Builder, das wegwerfbare Dokument, die strikte Typisierung – folgt aus diesen.

Wie NextPDF daran herangeht

Die Prinzipien sind keine Plakatsätze. Sie zeigen sich in konkreten Formen im Quellcode und verstärken sich gegenseitig.

Die folgende Tabelle ordnet jedem Prinzip zu, wo Sie es in der Engine sehen können und was es kostet, wenn es fehlt.

Prinzip	Wie es sich in NextPDF zeigt	Die Kosten des Gegenteils
Explizit schlägt implizit	`setSignature(certInfo:, level:)` nimmt die PAdES-Stufe als erforderliches, benanntes Argument entgegen – es gibt keine „auto“-Stufe	Ein Dokument, das mit einem von der Verpflichtung nicht geforderten Profil signiert wurde und erst zum Validierungszeitpunkt auffällt
Schnell scheitern, laut scheitern	`save()` lehnt einen Stream-Wrapper- oder Null-Byte-Pfad vor dem Rendering ab; `setSignature()` gefolgt von `save()` wirft eine Ausnahme, statt eine unsignierte Datei auszugeben	Ein Schreibvorgang mit Path Traversal oder eine PDF, die unsigniert ist, im Archiv aber für signiert gehalten wird
Fehler sind eine API-Oberfläche	Eine abstrakte Basisausnahme, spezifische typisierte Unterklassen, jede stellt ein strukturiertes `getContext()` für Logs und APM bereit	Ein generischer Stacktrace und ein langer Nachmittag voller Vermutungen
Grenzen werden benannt	In-Process-Konformitätsprüfungen liefern Befunde und sagen ausdrücklich, dass das Urteil einem unabhängigen Validator zukommt	Der Fehlschluss „keine Ausnahme, also muss es konform sein“, den ein Prüfer widerlegt
Nichts verschlechtert sich stillschweigend	Der Archivierungs-Zeitstempelpfad verweigert die Rückgabe eines halb geschriebenen Profils, statt eines Profils auszugeben, dem das erforderliche Dictionary fehlt	Ein Long-Term-Validation-Profil, das stillschweigend keines ist

Zusammengenommen ergeben die Prinzipien eine klare Haltung: Die Engine gibt Ihnen lieber ein ehrliches „Nein“ als ein selbstbewusstes „Vielleicht“. Das ist kein Pessimismus. Es ist die Erkenntnis, dass eine PDF häufig ein rechtliches Artefakt ist. Ein rechtliches Artefakt, das falsch ist, ist schlimmer als eines, das nie erstellt wurde.

Was die Belege sagen

Diese Seite ist eine Evidence: Design principle -Aussage: Die Prinzipien sind bewusste Entscheidungen, begründet, nicht gemessen. Wo ein Prinzip in einer externen Disziplin einen Namen hat, knüpft die Seite daran an, damit die Begründung nicht bloß eine hausinterne Meinung ist.

Die Haltung „verweigern, statt in einem undefinierten Zustand weiterzulaufen“ ist die Fail-safe-Qualitätseigenschaft in Spec: ISO/IEC 25010 §3 – ein Produkt versetzt sich bei einem Fehler in einen sicheren Zustand. Fehlertoleranz, aus derselben Qualitätsfamilie, ist das Maß, in dem sich ein System trotz Fehlern weiterhin wie beabsichtigt verhält. NextPDF richtet diesen Aufwand auf das Erkennen und Anhalten, nicht auf das Verbergen des Fehlers.
Die Haltung „die Grenze vor der Übernahme nennen“ ist Erkennbarkeit der Eignung ( Spec: ISO/IEC 25010, §3.26 ): die Fähigkeit, die Eignung aus der Dokumentation und ersten Eindrücken zu beurteilen.
Der PDF-spezifische Grund, warum all dies wichtig ist, ist Spec: ISO 32000-2, §12.8 : Der Byte-Bereich einer Signatur schützt genau die Bytes, die er abdeckt, und nichts darüber hinaus; eine Engine, die ein signiertes Dokument „hilfsbereit“ umschreibt oder sich daran vorbeirät, hat überhaupt nicht geholfen.

Die einzelnen Prinzipien werden auf ihren eigenen Seiten anhand von echtem Engine-Quellcode demonstriert – Eine API, die sich weigert zu raten und Fehler als Funktion liefern den Evidence: Code-backed Nachweis. Diese Seite erklärt das Warum; jene Seiten zeigen das Was.

Praktisches Beispiel

Die Prinzipien werden in wenigen Zeilen alltäglicher Nutzung sichtbar. Der Signaturaufruf gibt die Absicht explizit an. Die Engine verweigert früh, statt etwas Irreführendes auszugeben.

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

Es geht nicht um die Mechanik der Signatur. Es geht darum, dass drei Prinzipien in einem Snippet sichtbar werden: Die Absicht wird angegeben (level:), der Fehler tritt früh und benannt auf, und die Engine weigert sich, ein Dokument zu erzeugen, das über seinen eigenen Zustand lügen würde.

Häufiges Missverständnis

Das häufigste Missverständnis ist, dass diese Prinzipien NextPDF „schwieriger zu verwenden“ machen. Sie machen es schwerer, es falsch zu nutzen. Ein erforderliches Argument ist ein stiller Standardwert weniger, von dem man überrascht werden kann. Eine frühe Ausnahme ist ein beschädigtes Artefakt weniger in einem Archiv. Die Reibung wird bewusst dort platziert, wo ein Fehler billig ist – an der Aufrufstelle, während der Entwicklung – statt dort, wo er teuer ist: in der Produktion, in einer Prüfung, vor Gericht.

Ein zweites Missverständnis ist, dass „meinungsstark“ „unflexibel“ bedeutet. Das ist nicht der Fall. Die Engine hat Überzeugungen über Korrektheit und Absicht, nicht über Ihr Dokument. Layout, Inhalt, Schriftarten und Struktur behalten Sie weiterhin vollständig in der Hand. Die Überzeugungen betreffen die Weigerung, in Ihrem Namen zu raten, wo eine Vermutung unsicher wäre.

Grenzen und Abgrenzungen

Diese Seite benennt die Designabsicht. Sie ist selbst keine Verhaltensspezifikation. Die Prinzipien beschreiben, wie Entscheidungen getroffen werden, keine Garantie für eine einzelne Methode. Der genaue Vertrag jeder Methode steht in der Referenz und auf ihrer eigenen Insider_-Seite mit dem dort ausgewiesenen Evidenzniveau.

Die Prinzipien sind auch keine absoluten physikalischen Gesetze. Sie sind Prioritäten, die mit Augenmaß angewandt werden. Wo zwei Prinzipien in Konflikt geraten (eine strengere Verweigerung gegenüber einem nachsichtigeren Standard), gibt die obige Prioritätsreihenfolge den Ausschlag. Ein bestimmtes Modul kann dennoch eine begründete Ausnahme dokumentieren. Ist das der Fall, wird diese Ausnahme schriftlich festgehalten, nicht angenommen.

Schließlich ist „Designprinzip“ hier die Evidenzgrundlage – mit Absicht. Diese Seite argumentiert. Sie misst keine Benchmarks. Aussagen, die zur Untermauerung eine Zahl, einen Test oder eine Klausel benötigen, werden auf den Seiten getroffen, die diese Belege führen, nicht hier.

Glossar

Designprinzip (Evidenzniveau) – eine Seite, deren Aussagen bewusste Designentscheidungen sind, die aus der Absicht heraus und durch bestätigende Standards begründet werden, statt durch einen Benchmark oder einen einzelnen Test gemessen zu werden.
Fail-safe – eine Softwarequalitätseigenschaft: Bei einem Fehler kehrt das Produkt in einen sicheren Zustand zurück, statt in einem undefinierten Zustand weiterzulaufen. Der Grund, warum NextPDF verweigert, statt zu raten.
Fail fast – eine ungültige Eingabe zum frühestmöglichen Zeitpunkt mit klarer Ursache ablehnen, statt fortzufahren und später undurchsichtig zu scheitern.
PAdES – PDF Advanced Electronic Signatures, die ETSI-Profilfamilie zum Signieren von PDF-Dokumenten (B-B, B-T, B-LT, B-LTA). Hier bei der ersten Verwendung ausgeschrieben; ausführlich behandelt auf den Signierseiten.
Notwendig, nicht hinreichend – eine bewusste Formulierung, die verwendet wird, wenn eine In-Process-Prüfung ein echtes Signal ist, aber kein Konformitätsurteil; die maßgebliche Entscheidung kommt einem unabhängigen Validator zu.