Das Pipeline-Modell

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

Auf einen Blick

Ein NextPDF-Dokument entsteht nicht in einem einzigen undurchsichtigen Schritt. Es durchläuft eine kleine Zahl expliziter Stufen: eine Fassade, die die Absicht festhält, eine Inhaltsschicht, die diese Absicht in ein Modell überführt, und einen Writer, der dieses Modell in ein konformes PDF serialisiert. Diese Seite erklärt diese Form und warum sie bewusst so gewählt ist.

Warum das wichtig ist

Das PDF-Dateiformat ist selbst eine geschichtete Struktur — ein Header, ein Rumpf aus Objekten, eine Querverweistabelle und ein Trailer — und ein Writer muss all das konsistent zusammensetzen. Wenn die Engine, die diese Struktur erzeugt, eine einzige verworrene Prozedur ist, gefährdet jede Änderung jede Ausgabe. Die einzige Möglichkeit, Vertrauen zu gewinnen, besteht dann darin, ganze Dokumente zu rendern und sie mit bloßem Auge zu prüfen. Das ist langsam, spät und wenig belastbar.

Eine explizite Pipeline kehrt das um. Jede Stufe hat eine Aufgabe und eine typisierte Grenze, sodass Sie über eine Änderung nachdenken und sie genau an der Stufe testen können, die sie berührt, statt erst am Ende der Datei. Die Architektur ist vor allem eine Entscheidung für Testbarkeit und Erweiterbarkeit.

Die Kurzfassung

• Der öffentliche Einstiegspunkt ist eine Document-Fassade. Sie ist ein fließender, nur einmal verwendbarer, Worker-sicherer Builder, der festhält, was Sie wollen, nicht wie es serialisiert wird.
• Die Fassade delegiert an rund zwei Dutzend fokussierte Concern Traits (Textausgabe, Zeichnen, Seiten, Sicherheit, Navigation und so weiter) — jeweils mit einer Verantwortlichkeit, statt alles in einer einzigen riesigen Klasse zu bündeln.
• Inhalt gelangt über einen von zwei Pfaden in die Pipeline: direktes Zeichnen (Grafikprimitive) oder die HTML/CSS-Engine. Beide erzeugen dasselbe interne Dokumentmodell.
• Ein dedizierter PDF-Writer serialisiert dieses Modell und wählt eine Strategie für PDF 1.4 / 1.7 / 2.0. Das Erzeugen einer gültigen Dateistruktur findet hier statt und nirgendwo sonst.
• Langlebiger Zustand (Schriften- und Bild-Registries) ist prozessbezogen und gemeinsam genutzt; Zustand pro Anfrage (das Dokument) wird frisch erzeugt und nie wiederverwendet. Die Grenze ist explizit, und genau das macht Worker-Laufzeiten sicher.

Wie NextPDF das angeht

Am klarsten wird das Modell, wenn man ein Dokument vom Aufruf bis zu den Bytes verfolgt.

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.

Der Weg eines Dokuments durch NextPDF: Jede Stufe hat eine Verantwortlichkeit und eine typisierte Grenze, sodass sie isoliert durchdacht und getestet werden kann.

Zwei Designentscheidungen machen daraus mehr als ein Diagramm.

Die Fassade ist zusammengesetzt, nicht monolithisch. Die Klasse Document implementiert nicht jedes Feature selbst; sie delegiert jeden Bereich an ein dediziertes Concern Trait — Textausgabe, Zeichnen, Seiten, Sicherheit, Typografie, Navigation, Transaktionen und so weiter. Eine neue Dokumentmethode gehört in das Trait, das ihren Bereich besitzt, nicht in die Fassade selbst. Die Klasse, die Sie aufrufen, bleibt klein, und die Verantwortlichkeiten bleiben getrennt.

Der Writer besitzt die Dateistruktur exklusiv. Die Inhaltserzeugung entscheidet, welche Markierungen und Objekte existieren; der Writer entscheidet, wie sie zu einer gültigen PDF-Datei werden, einschließlich der anzuwendenden Versionsstrategie. Diese Trennung wird als Architekturregel durchgesetzt: Layout- und Inhaltscode geben keine endgültige Dateistruktur aus, und der Writer trifft keine Layout-Entscheidungen. Der Vorteil ist, dass die Frage „Ist die Ausgabe ein gültiges PDF?“ genau an einer Stelle getestet wird.

Die Lebensdauergrenze ist Teil des Modells, kein nachträglicher Einfall. Schriften- und Bild-Registries leben für die Dauer des Prozesses und werden über Anfragen hinweg gemeinsam genutzt; das Dokument, sein Rendering-Kontext und der Writer werden pro Anfrage erzeugt und verworfen. In einer Worker-Laufzeit entscheidet diese Unterscheidung über sichere Wiederverwendung oder anfragenübergreifende Beschädigung. Aus diesem Grund ist sie in der Architektur festgehalten und nicht der bloßen Disziplin überlassen.

Was die Belege sagen

Diese Seite ist Evidence { } Code-backed Evidence: Code-backed . Die Stufen entsprechen einer realen Struktur im Core-Repository:

• Die Fassade und ihre Delegation entsprechen src/Core/Document.php plus den Concern Traits in src/Core/Concerns/ (Textausgabe, Ausgabe, Zeichnen, Seiten, Sicherheit, Typografie, Navigation, Transaktionen und mehr — jeweils eine einzige Verantwortlichkeit).
• Die zwei Inhaltspfade sind die HTML/CSS-Engine (src/Html/) und direktes Zeichnen (src/Graphics/), die beide das interne Modell speisen.
• Serialisierung und PDF-Versionsstrategie liegen in src/Writer/ (PdfWriter.php, mit expliziten Strategieklassen für PDF 1.4 / 1.7 / 2.0).
• Die Grenze zwischen prozessbezogenem und anfragebezogenem Zustand ist das Worker-sichere Design, das in der Architekturübersicht festgehalten und vom mitgelieferten Worker-Factory-Beispiel erprobt wird, das eine FontRegistry und eine ImageRegistry über Anfragen hinweg gemeinsam nutzt und dabei jedes Document frisch erzeugt.

Das Ergebnis ist durch das Format fest vorgegeben. Die Ausgabe des Writers muss aus einem Header, einem Objektrumpf, einer Querverweistabelle und einem Trailer bestehen, gemäß Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 . Diese Verpflichtung in einer Stufe zu bündeln, ermöglicht es dem Rest der Engine, auf Inhalt fokussiert zu bleiben, statt auf das Zusammensetzen der Dateistruktur.

Praktisches Beispiel

Die Aufgabe der Fassade ist es, Absicht auch als solche lesbar zu machen. Der Inhaltspfad und der Writer bleiben an der Aufrufstelle unsichtbar:

<?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

Jeder Aufruf wird von einem anderen Concern verarbeitet. Zwei verschiedene Inhaltspfade speisen dasselbe Modell. Genau eine Stufe — save() — macht aus dem Modell Dateibytes. Nichts an der Aufrufstelle muss wissen, wie die Querverweistabelle aufgebaut wird.

Häufiges Missverständnis

Das häufige Missverständnis ist, dass „Pipeline“ eine streamende Push-API bedeutet, die man Stufe für Stufe verdrahtet, wie eine Unix-Pipe. Das tut sie nicht. Diese Pipeline ist eine architektonische Zerlegung: Stufen mit einzelnen Verantwortlichkeiten und typisierten Grenzen. Sie programmieren weiterhin über eine fließende Fassade. Die Stufen beschreiben, wie die Engine gebaut und getestet wird, nicht einen Transportweg, den Sie von Hand zusammensetzen.

Ein verwandtes Missverständnis ist die Annahme, die Fassade sei die Engine. Sie ist der Einstiegspunkt. Die eigentliche Arbeit verteilt sich auf Concern Traits, zwei Inhaltspfade und einen Writer. Genau diese Verteilung ist der Grund, warum eine einzelne Feature-Änderung nicht jede Ausgabe gefährdet.

Human-factors note: Human-factors note

Dieselbe fünfstufige Abfolge wird im Diagramm, in der Kurzfassung, in den Belegen und im Beispiel verwendet — bewusst. Eine konsistente Struktur, der der Leser einmal begegnet und die er dann überall wiedererkennt, senkt den Aufwand, der Seite zu folgen. Das spiegelt wider, warum die Engine selbst die Stufengrenzen fest und wenige statt viele und fließende hält.

Grenzen und Abgrenzungen

Diese Seite beschreibt die Form der Pipeline, nicht die interne API einer einzelnen Stufe. Das genaue Inventar der Concern Traits, die Auswahlregeln für die Writer-Strategie und die Felder des Inhaltsmodells werden durch den Code und die Referenz definiert, nicht durch diese Erklärung. Die genaue Anzahl der Traits ist ein Implementierungsdetail, das sich ändern kann, ohne das Modell zu ändern. Diese Seite behandelt weder die internen Stufen der HTML-Engine (ein eigenes Thema) noch das Streaming- und Speicherverhalten des Writers (ebenfalls eigenständig). Die strukturellen Aussagen sind zum Prüfdatum dieser Seite zutreffend; die maßgeblichen Quellen sind src/Core/, src/Html/, src/Graphics/ und src/Writer/ des Core-Repositorys.

Das Pipeline-Modell ist über alle Editionen hinweg identisch; Editionen fügen Fähigkeiten innerhalb der Stufen hinzu, keine neuen Stufen:

Pipeline model — edition availability

Edition	Availability
Core	○ Core implementiert die vollständige Pipeline Fassade → Inhalt → Writer.
Pro	○ Pro fügt Fähigkeiten innerhalb bestehender Stufen hinzu, keine neuen Stufen.
Enterprise	○ Enterprise fügt Fähigkeiten innerhalb bestehender Stufen hinzu, keine neuen Stufen.

Verwandte Dokumente

• Speicher und Streaming — wie die Writer-Stufe den Speicher begrenzt hält.
• Die HTML-Pipeline — die internen Stufen des HTML-Inhaltspfads.
• Strikte Typen, überall — die typisierten Grenzen, die jede Stufe unabhängig testbar machen.

Glossar

• Fassade — der öffentliche Document-Einstiegspunkt: ein fließender, nur einmal verwendbarer Builder, der die Absicht festhält und an Concern Traits delegiert.
• Concern Trait — ein fokussiertes PHP-Trait, das die Fassade komponiert und jeweils einen einzelnen Funktionsbereich besitzt (Textausgabe, Zeichnen, Seiten, Sicherheit und so weiter).
• Inhaltspfad — eine der beiden Arten, wie Inhalt in das Modell gelangt: direktes Zeichnen oder die HTML/CSS-Engine.
• Dokumentmodell — die interne, typisierte Ansammlung von Seiten, Inhalt und Ressourcen der Engine vor der Serialisierung.
• Writer-Stufe — die Komponente, die das Modell in ein gültiges PDF serialisiert und dabei eine Strategie für PDF 1.4 / 1.7 / 2.0 auswählt.
• Worker-sicher — so entworfen, dass Zustand mit Prozesslebensdauer sicher gemeinsam genutzt wird, während anfragebezogener Zustand frisch erzeugt und nie wiederverwendet wird.