PHP-8.4-Grundlagen

Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 Evidence { } Code-backed Evidence: Code-backed PHP-Einschränkung ≥8.4 <9.0 PHP-Einschränkung: ≥8.4 <9.0

Auf einen Blick

NextPDF setzt PHP 8.4 voraus. Diese Seite erklärt, auf welche Sprachfeatures von 8.4 die Engine tatsächlich angewiesen ist, warum diese Version eine feste Untergrenze und keine höfliche Empfehlung ist und wie ein separater Downgrade-Build den Betrieb auf einer älteren Laufzeit ermöglicht, ohne die Codebasis zu schwächen, die Sie hier lesen.

Warum das wichtig ist

Eine PDF-Engine verwandelt mehrdeutige Eingaben in ein bytegenaues Dateiformat. PDF ist ein seit Langem etabliertes Format mit festen, unveränderlichen Regeln, und es ist streng genug, dass eine falsche Vermutung teuer werden kann. Die Programmiersprache der Engine ist die erste Stelle, an der solche Vermutungen entweder abgefangen oder ungeprüft durchgereicht werden. Eine Versionsuntergrenze ist keine Einschränkung um ihrer selbst willen. Sie markiert die Linie, unterhalb derer die Engine die Typgarantien nicht mehr geben kann, auf denen der Rest ihres Designs beruht.

Wenn diese Untergrenze vage bleibt, entstehen zwei Kosten. Die Codebasis füllt sich mit Kompatibilitäts-Shims, die die eigentliche Logik verschleiern. Außerdem verliert das Typsystem seine tragende Rolle, und genau das kann sich eine Dokument-Pipeline nicht leisten.

Die Kurzfassung

• Das Core-Paket deklariert "php": ">=8.4 <9.0". Das ist die tatsächliche Einschränkung, verifiziert in composer.json, und keine bloße Dokumentationsbehauptung.
• 8.4 ist die Untergrenze, weil die Engine Sprachfeatures aus 8.4 und aktuellen 8.x-Versionen als strukturelle Garantien nutzt: asymmetrische Sichtbarkeit, Backed Enums mit Verhalten, typisierte Klassenkonstanten, Readonly-Zustand und benannte Argumente als festen Bestandteil der öffentlichen API.
• Der Betrieb auf PHP 8.1–8.3 ist über einen separaten Downgrade-Build (den Backport) weiterhin möglich. Es handelt sich um Build-Werkzeuge, nicht um eine Laufzeitabhängigkeit. Er ändert nichts am Code, den Sie im Core-Repository lesen.
• Die Obergrenze <9.0 ist bewusst gewählt: Ein neues PHP-Major-Release wird als etwas behandelt, das validiert und nicht vorausgesetzt werden muss.

Wie NextPDF damit umgeht

Die Untergrenze ergibt sich aus dem, was der Code tut. Deshalb ist es am transparentesten, die Features im Code zu zeigen, statt sie abstrakt aufzulisten.

Asymmetrische Sichtbarkeit macht Zustand öffentlich lesbar, aber nur privat beschreibbar, ohne einen handgeschriebenen Getter für jedes Feld. Der Rendering-Kontext nutzt sie direkt:

declare(strict_types=1);

final class RenderingContext
{
    // Readable everywhere, writable only inside the class.
    public private(set) float $x = 0.0;
    public private(set) float $y = 0.0;
    public private(set) int $currentPageIndex = -1;
    public private(set) string $currentContentStream = '';
}

Dieses eine Sprachfeature beseitigt eine ganze Kategorie versehentlicher externer Mutation. Der Cursor kann nicht von außerhalb der Engine bewegt werden. Die Garantie wird von der Laufzeit erzwungen, nicht von einer Konvention, die Reviewer im Kopf behalten müssen.

Backed Enums mit Verhalten ersetzen verstreute boolesche Flags und String-Konstanten durch einen einzigen typisierten Wert, der zudem Fragen über sich selbst beantworten kann. Der Diskriminator für die Dokumentkonformität ist ein Backed Enum, dessen Methoden Entscheidungen auf Spezifikationsebene treffen:

declare(strict_types=1);

enum ConformanceMode: string
{
    case Plain  = 'plain';
    case PdfUa2 = 'pdfua2';
    case PdfA4  = 'pdfa4';
    case PdfA4f = 'pdfa4f';

    public function isTagged(): bool
    {
        return match ($this) {
            self::Plain => false,
            default     => true,
        };
    }

    /** @return 2|3|4|null */
    public function pdfaPart(): ?int
    {
        return match ($this) {
            self::PdfA4, self::PdfA4f => 4,
            default                   => null,
        };
    }
}

Das Enum ist die einzige Quelle der Wahrheit für “Ist dieses Dokument spezifikationskonform getaggt?” und “Welcher ISO-Teil gilt?”. Werden solche Fragen über einzelne Booleans ausgedrückt, können mehrere Stellen sie inkonsistent beantworten.

Typisierte Klassenkonstanten machen selbst Konstanten zum Bestandteil des Typvertrags. Die harten Grenzen der HTML-Engine sind als typisierte Konstanten deklariert:

private const int MAX_NESTING_DEPTH = 100;
private const int MAX_ELEMENT_COUNT = 50_000;

Benannte Argumente sind Teil der öffentlichen API-Oberfläche, kein interner Kunstgriff. Die Beispielprogramme übergeben sie an Aufrufstellen, die Leser kopieren sollen:

$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);

Das sind keine dekorativen Verwendungen neuer Syntax. Jede einzelne wandelt eine Konvention, die ein Reviewer andernfalls von Hand durchsetzen müsste, in eine Eigenschaft um, die von der Laufzeit erzwungen wird.

Was die Belege sagen

Diese Seite ist Evidence { } Code-backed Evidence: Code-backed . Jede Aussage oben verweist auf eine Datei im Core-Repository, nicht auf eine Feature-Liste:

• Die Versionseinschränkung ist der Wert für require.php ">=8.4 <9.0" in der Core-composer.json.
• Das Beispiel zur asymmetrischen Sichtbarkeit ist der tatsächliche Deklarationsstil in src/Core/RenderingContext.php (public private(set)-Felder).
• Das Enum-Beispiel entspricht src/Conformance/ConformanceMode.php, einem Backed enum … : string, dessen match-basierte Methoden Konformitätsentscheidungen steuern.
• Die typisierten Konstanten sind src/Html/HtmlParser.php (private const int MAX_NESTING_DEPTH, MAX_ELEMENT_COUNT).
• Der Aufruf mit benanntem Argument stammt aus den ausgelieferten examples/-Programmen.

Die Untergrenze hat zudem eine Standards-Dimension. Die Aufgabe der Engine besteht darin, Dateien auszugeben, die Spec Spec: ISO 32000-2, §7.5.2 ISO 32000-2 §7.5.2 . Ein konformer PDF-2.0- Writer muss die Dokumentversion im Datei-Header oder im Katalog als 2.0 deklarieren. Eine derart exakte Verpflichtung lässt sich weitaus zuverlässiger erfüllen, wenn die Programmiersprache, auf der der Writer aufsetzt, es von vornherein erschwert, nicht zusammenpassenden Zustand zu konstruieren. Die Versionsuntergrenze und die Strenge des Formats greifen hier ineinander.

Praktisches Beispiel

Schon das kleinste korrekte Programm setzt die Untergrenze voraus. Es läuft auf PHP 8.4, verwendet ein benanntes Argument und erzeugt eine konforme Datei:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->save(__DIR__ . '/hello.pdf');

Nichts hier ist exotisch. Entscheidend ist, dass dieselbe Maschinerie aus strenger Typisierung, Enums und asymmetrischer Sichtbarkeit, die die Engine-Interna vertrauenswürdig macht, bereits unter diesem fünfzeiligen Programm aktiv ist. Sie müssen sie nicht eigens aktivieren.

Häufiges Missverständnis

Das häufigste Missverständnis ist, dass “setzt PHP 8.4 voraus” bedeutet “läuft nicht, solange Sie nicht auf 8.4 aktualisieren.” Gemeint ist, dass der Core-Quellcode auf 8.4 abzielt. Für Teams, die auf PHP 8.1–8.3 festgelegt sind, existiert ein separater Downgrade-Build.

Wichtig ist die genaue Abgrenzung dieses Builds. Er ist eine Rector-basierte Downgrade-Pipeline, die den 8.4-Quellcode in eine Ausgabe mit älterer Syntax umwandelt. Das ist Build-Infrastruktur, keine Laufzeitbibliothek, die Sie den Abhängigkeiten Ihrer Anwendung hinzufügen. Sie führt keine parallele, schwächer typisierte Codebasis ein. Der auf diesen Seiten geprüfte Code und der ausgelieferte Code bleiben derselbe Code. Der Backport ist eine darauf angewandte Transformation, keine Alternative dazu.

Human-factors note: Human-factors note

Diese Seite zeigt bewusst vier kurze, reale Codebeispiele statt einer langen Prosa-Liste von Sprachfeatures. Verwandte Ideen werden gruppiert und bewusst auf wenige Beispiele begrenzt. Eine kleine Auswahl konkreter Beispiele lässt sich leichter im Kopf behalten und später wiedererkennen als ein erschöpfender Katalog. Dieselbe Überlegung hält auch die eigene Typoberfläche der Engine klein und explizit statt breit und implizit.

Grenzen und Abgrenzungen

Diese Seite erklärt, warum 8.4 die Untergrenze ist und was der Backport bewahrt. Sie dokumentiert nicht, wie die Downgrade-Pipeline ausgeführt wird, welche Zielversionen unterstützt werden oder welche betrieblichen Vorbehalte gelten. Das gehört in die eigene Dokumentation des Backport-Builds. Das interne Paketlayout dieser Werkzeuge liegt hier außerhalb des Geltungsbereichs. Die gezeigten Feature-Verwendungen veranschaulichen den Stil der Engine. Sie sind nicht das vollständige Inventar jedes 8.x-Features, das die Codebasis nutzt. Die genauen APIs definiert die Referenz, nicht diese Erläuterung. Die Versionseinschränkung ist zum Prüfdatum dieser Seite zutreffend. Der maßgebliche Wert ist stets der require-Block in der Core-composer.json.

Die Edition hat keinen Einfluss auf die Sprachuntergrenze. Jede Edition wird aus demselben PHP-8.4-Quellcode gebaut:

PHP 8.4 source floor — edition availability

Edition	Availability
Core	○ Core ist gegen PHP 8.4 geschrieben.
Pro	○ Pro baut auf derselben 8.4-Quellcode-Untergrenze auf.
Enterprise	○ Enterprise baut auf derselben 8.4-Quellcode-Untergrenze auf.

Verwandte Dokumente

• Strikte Typen, überall — wie die Disziplin der statischen Analyse die Sprachuntergrenze in eine Garantie verwandelt.
• Das Pipeline-Modell — die Architektur, die diese Sprachfeatures zusammenhält.
• Die NextPDF-Designphilosophie — warum die Engine explizite, von der Laufzeit erzwungene Verträge bevorzugt.

Glossar

• Versionsuntergrenze — die minimale PHP-Version, auf die der Core-Quellcode abzielt (>=8.4). Darunter lassen sich die Typgarantien der Engine nicht ausdrücken.
• Asymmetrische Sichtbarkeit — ein PHP-8.4-Feature, das es einer Eigenschaft erlaubt, öffentlich lesbar, aber nur aus einem engeren Geltungsbereich beschreibbar zu sein (public private(set)).
• Backed Enum — ein PHP-Enum, dessen Fälle skalare Werte haben und das Verhalten (Methoden) tragen kann, hier als einzige typisierte Quelle der Wahrheit verwendet.
• Backport — der separate, Rector-basierte Downgrade-Build, der den 8.4-Quellcode in eine auf älterem PHP lauffähige Ausgabe umwandelt. Er besteht aus Build-Werkzeugen, nicht aus einer Laufzeitabhängigkeit.
• Konformitätsmodus — der typisierte Diskriminator der Engine, der festlegt, welchen ISO-Konformitätsvertrag ein Dokument erfüllen muss.