Die HTML-Pipeline

Spec Spec: CSS Cascade 5, §6.1 CSS Cascade 5 §6.1 Spec Spec: CSS Display 3, §2 CSS Display 3 §2 Evidence { } Code-backed Evidence: Code-backed

Auf einen Blick

NextPDF rendert HTML und CSS innerhalb Ihres PHP-Prozesses zu PDF — ohne Browser und standardmäßig ohne Subprozess. Diese Seite erläutert die aufeinander aufbauenden Stufen einer Konvertierung, welche Bereiche die CSS-Engine tatsächlich abdeckt und wann die Delegation an einen echten Browser-Renderer die ehrliche Wahl ist.

Warum das wichtig ist

„HTML zu PDF“ klingt nach einem einzigen Vorgang. Tatsächlich stehen dahinter Kaskade, Boxmodell, Layout-Durchlauf und Paint-Durchlauf. Jeder dieser Schritte ist ein klar spezifiziertes Problem mit eigenen Fehlermodi. Eine Engine, die sie zu einer einzigen Prozedur verschmilzt, ist fragil. Eine Änderung am Farbparsing kann eine Box verschieben; erkennen lässt sich das nur, indem man rendert und das Ergebnis prüft.

Das prozessinterne Modell hat einen echten Vorteil: Es gibt keinen Browser, der installiert werden muss, keine Sandbox, die betrieben werden muss, und keine Prozessgrenze, über die hinweg gemarshallt werden muss. Doch es zahlt sich nur aus, wenn die Konvertierung sauber genug zerlegt ist, um jeden Aspekt einzeln testen zu können. Erst die Architektur macht „HTML in PHP rendern“ vertrauenswürdig und nicht nur möglich.

Die Kurzfassung

• Die HTML-/CSS-Konvertierung läuft prozessintern über writeHtml(). Das Ergebnis ist nativer PDF-Inhalt, kein Abbild einer Seite.
• Sie ist einphasig und streamend. Der Tokenizer erzeugt eine Token-Liste. Der Parser verarbeitet sie von links nach rechts, und es wird kein vollständiger DOM-Baum vorgehalten (ADR-001). Feste Obergrenzen beschränken Elementanzahl und Verschachtelungstiefe.
• Die Engine ist als explizite Schichten organisiert: CSS-Parsing und Applikatoren, Stilzustand, Layout und Formatierung, Paint sowie Paged Media — mit strengen Regeln dazu, welche Schicht was tun darf (ADR-010).
• Die CSS-Engine deckt die Kaskade, das Boxmodell und gängiges Layout ab (Block, Inline, Tabellen, Floats und mehr) — umfangreich, aber eine definierte Teilmenge dessen, was ein moderner Browser implementiert.
• Wenn Sie für beliebiges modernes CSS exakte Browser-Treue benötigen, kann NextPDF über eine optionale Erweiterung an einen Headless-Browser-Renderer delegieren — eine bewusst gesetzte, netzwerkisolierte Nahtstelle, nicht der Standardpfad.

Wie NextPDF es angeht

Die Konvertierung ist eine Abfolge von Stufen, von denen jede die typisierte Ausgabe der vorherigen Stufe verarbeitet.

1. Tokenize HTML becomes an ordered token list — no retained DOM tree.
2. Resolve CSS Parse styles; the cascade and applicators compute typed values.
3. Style state A push/pop style stack carries computed values per nesting level.
4. Layout Block, inline, table, and float geometry computed; no paint here.
5. Paint Borders, backgrounds, text, and decorations emit PDF operators.
6. Paged media Page-break and @page rules applied as the cursor crosses page bounds.

Die prozessinterne HTML-Pipeline: ein einziger Durchlauf von links nach rechts über einen Token-Stream, mit CSS-Auflösung, Stilzustand, Layout und Paint als getrennten Schichten und Paged-Media-Umbrüchen, die angewendet werden, während der Cursor voranschreitet.

Zwei architektonische Regeln machen daraus mehr als nur einen Ablauf.

Schichten haben Verträge. CSS-Text wird ausschließlich innerhalb von Applikatorklassen gelesen. Layout-Code berechnet Geometrie, gibt aber keine Paint-Operatoren aus. Paint-Code liest einen unveränderlichen Snapshot des berechneten Stils, niemals den veränderlichen Layout-Tracking-Zustand. Paged-Media-Code löst Umbrüche aus, delegiert die Seitendekoration jedoch an die Paint-Schicht. Diese Grenzen werden erzwungen (ADR-010). Deshalb ist eine neue CSS-Eigenschaft ein neuer Applikator und keine Änderung, die gleichzeitig durch Parser, Layout-Dispatch und Painter wirkt.

Es gibt kein DOM. Die Pipeline ist per Entscheidung einphasig und streamend (ADR-001): höchstens ein Stilzustand pro Verschachtelungsebene plus der aktive Cursor, nicht ein Objekt pro Element. Einige wenige Operationen benötigen tatsächlich Look-ahead — die Spaltenbemessung von Tabellen, :has(), :last-child. Diese werden über begrenzte Pre-Scan-Indexstrukturen auf der flachen Token-Liste behandelt, nicht durch das Vorhalten eines Baums. Elementanzahl und Verschachtelungstiefe sind hart begrenzt, sodass eine pathologische Eingabe schnell fehlschlägt, statt den Speicher zu erschöpfen.

Die CSS-Engine wertet echte CSS-Semantik aus, keine bloße Nachbildung. Konkurrierende Deklarationen werden nach Ursprung, Wichtigkeit, Layer, Spezifität und Reihenfolge auf einen Wert pro Eigenschaft reduziert — die eigentliche Kaskade. Das Layout folgt dem Boxmodell. Der Typ einer Box und der von ihr etablierte Formatierungskontext entscheiden, wie sie und ihre im Fluss befindlichen Geschwister platziert werden. Der Quellcode der Engine ist genau um diese Belange herum organisiert (Kaskade, box/display, Flex, Float, Tabellen, Fragmentierung). Deshalb können Sie ihr Verhalten aus den Spezifikationen ableiten, statt es empirisch ermitteln zu müssen.

Was die Belege sagen

Diese Seite ist Evidence { } Code-backed Evidence: Code-backed . Die Stufen und Regeln lassen sich dem Core-Repository zuordnen:

• Der prozessinterne Einstiegspunkt ist writeHtml(string $html): static in src/Core/Concerns/HasTextOutput.php.
• Das einphasige Design ohne vorgehaltenes DOM mit Element- und Verschachtelungsgrenzen ist in ADR-001 sowie im Tokenizer-/Parser-/Stil-Stack-Code in src/Html/ beschrieben.
• Der Vertrag der geschichteten Engine — CSS-Parsing/Applicators, Stilzustand, Layout, Paint, Paged Media — ist ADR-010 und im Aufbau von src/Html/ abgebildet (zum Beispiel Cascade/, Css/, Flex/, Float/, Fragmentation/ und die Applikatorklassen).
• Die Nahtstelle für die Browser-Delegation ist writeHtmlChrome() in derselben Datei, dokumentiert als erforderlich für die optionale Renderer-Erweiterung samt einem Chrome-/Chromium-Binary.

Die Standards stützen die Abdeckungsaussage und machen ihre Grenzen nachvollziehbar. Die Kaskade reduziert konkurrierende Deklarationen auf einen einzigen Wert pro Eigenschaft — Ursprung, Wichtigkeit, Layer, Spezifität, Reihenfolge — gemäß Spec Spec: CSS Cascade 5, §6.1 CSS Cascade 5 §6.1 , und die Platzierung im Fluss folgt Box- und Formatierungskontext-Regeln gemäß Spec Spec: CSS Display 3, §2 CSS Display 3 §2 . Ebenso wichtig ist die Grenze: Eine Feature-Query existiert gerade deshalb, weil nicht jeder Prozessor jedes Feature unterstützt gemäß Spec Spec: CSS Conditional 5, §2 CSS Conditional 5 §2 . Die CSS-Engine von NextPDF ist eine definierte, an Spezifikationen ausgerichtete Teilmenge; das klar auszusprechen ist Teil des Vertrags.

Praktisches Beispiel

Prozessinternes Rendering ist ein einziger Aufruf. Die Ausgabe ist auswählbarer PDF-Text, keine gerasterte Seite:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">HTML Rendering in NextPDF</h1>
<p>NextPDF renders <strong>HTML and CSS</strong> directly into PDF pages,
<em>in-process</em>.</p>
<ul>
  <li>Headings, paragraphs, bold and italic</li>
  <li>Lists, tables, inline styles</li>
</ul>
HTML;

$doc->writeHtml($html);
$doc->save(__DIR__ . '/html-basic.pdf');

Wenn dasselbe Dokument beliebiges modernes CSS mit exakter Browser-Treue erfordern würde, lautete der Aufruf stattdessen writeHtmlChrome($html) — dasselbe Dokument, ein anderer Rendering-Pfad und eine bewusste Abhängigkeit vom optionalen Browser-Renderer.

Verbreitetes Missverständnis

Das wiederkehrende Missverständnis ist, dass eine HTML-zu-PDF-Engine „im Grunde ein Browser“ sei. Das ist sie nicht, und sie erhebt auch keinen solchen Anspruch. Ein Browser ist eine riesige, fortlaufend aktualisierte Implementierung der gesamten Webplattform. Die prozessinterne Engine von NextPDF ist eine an Spezifikationen ausgerichtete Teilmenge mit Fokus auf Dokumentlayout. Das ehrliche mentale Modell ist „eine kompetente CSS-Engine für Druckdokumente“, nicht „Chrome in PHP“. Wenn Sie wirklich die volle Plattform benötigen, ist genau dafür writeHtmlChrome() da. Es ist ein separater Opt-in-Pfad mit eigenem Betriebsaufwand, kein stiller Fallback.

Ein zweites Missverständnis ist die Annahme, der Browser-Pfad bedeute lediglich, „die Seite über das Netzwerk zu rendern“. Konstruktionsbedingt ist das Gegenteil der Fall. Die Delegationsnahtstelle rendert mit bedingungslos blockiertem Netzwerkzugriff auf Subressourcen — keine entfernten Bilder, Schriften, Stylesheets oder Frames —, sodass sie nicht zu einem Vektor für ausgehende Anfragen werden kann. Pixel-Treue, ja; ein offener Netzwerkausgang, nein.

Human-factors note: Human-factors note

Diese Seite benennt die Abdeckungsgrenze direkt, statt vollständige CSS-Unterstützung zu suggerieren und die Lesenden diese Grenze selbst entdecken zu lassen. Die Grenze dort zu nennen, wo die Fähigkeit beschrieben wird — statt sie zu verstecken —, ermöglicht erfahrenen Engineers eine Integrationsentscheidung, die sich vertreten lässt. Das ist der eigentliche Grund, warum es in CSS überhaupt einen Mechanismus für Feature-Queries gibt.

Grenzen und Abgrenzungen

Diese Seite erläutert die Gestalt der Pipeline und die Wahl zwischen prozessinternem Pfad und Browser-Pfad. Sie ist keine CSS-Support-Matrix. Welche genauen Eigenschaften, Module und Selektoren die prozessinterne Engine abdeckt, wird durch den Code und seine Konformitätstests definiert, nicht durch diesen Überblick. Diese Abdeckung entwickelt sich weiter. Der Pfad für die Browser-Delegation erfordert eine optionale Erweiterung und ein Chrome-/Chromium-Binary. Einrichtung, Betriebseigenschaften und interner Aufbau dieser Erweiterung sind nicht Gegenstand dieser Seite und werden zusammen mit diesem Paket dokumentiert. „Prozessintern“ beschreibt den Standardpfad writeHtml(). Das ist keine Behauptung, dass jeder Rendering-Pfad einen Subprozess vermeidet. Die architektonischen Aussagen sind zum Prüfdatum dieser Seite zutreffend. Die maßgeblichen Quellen sind src/Html/, ADR-001 und ADR-010 im Core-Repository.

Die prozessinterne CSS-Engine ist eine Core-Fähigkeit. Die Nahtstelle für die Browser-Delegation ist eine optionale Erweiterung, hier nur auf Fähigkeitsebene aufgeführt:

HTML rendering paths — edition availability

Edition	Availability
Core	○ Core stellt die prozessinterne HTML-/CSS-Engine bereit (writeHtml).
Pro	○ Der Pfad für die Browser-Delegation ist eine optionale Zusatzerweiterung, unabhängig von der Edition-Stufe.
Enterprise	○ Der Pfad für die Browser-Delegation ist eine optionale Zusatzerweiterung, unabhängig von der Edition-Stufe.

Verwandte Dokumentation

• Das Pipeline-Modell — wo der HTML-Inhaltspfad im Gesamtfluss des Dokuments verortet ist.
• Wann NextPDF nicht zu verwenden ist — die ehrliche Abgrenzung, einschließlich der Frage, wann der Browser-Pfad oder ein anderes Werkzeug geeignet ist.
• Der Leitfaden zur Integrationsentscheidung — die Wahl zwischen der prozessinternen Engine und einem Renderer für Ihren Fall.

Glossar

• Prozessinternes Rendering — die Konvertierung von HTML/CSS in PDF innerhalb des PHP-Prozesses, ohne Browser oder standardmäßigen Subprozess (writeHtml()).
• Einphasig / streamend — das Verarbeiten eines Token-Streams von links nach rechts, ohne einen vollständigen DOM-Baum vorzuhalten (ADR-001).
• Kaskade — der CSS-Prozess, der konkurrierende Deklarationen nach Ursprung, Wichtigkeit, Layer, Spezifität und Reihenfolge auf einen Wert pro Eigenschaft auflöst.
• Formatierungskontext — die Layout-Umgebung, die eine Box etabliert und die bestimmt, wie ihre im Fluss befindlichen Inhalte platziert werden.
• Engine-Schichtvertrag — das erzwungene Regelwerk (ADR-010), das definiert, was die Schichten für Parsing, Stil, Layout, Paint und Paged Media jeweils tun dürfen.
• Browser-Delegationsnahtstelle — der optionale Pfad writeHtmlChrome(), der über einen Headless-Browser mit blockiertem Netzwerkzugriff auf Subressourcen rendert.