NextPDF Backport Builder – Überblick

Build-Werkzeug – KEINE Laufzeitabhängigkeit. NextPDF-Maintainer nutzen dieses Paket, um PHP-8.1+- und PHP-7.4+-kompatible Distributionen von NextPDF zu erzeugen. Anwendungen dürfen dieses Paket niemals als Laufzeitabhängigkeit einbinden.

Auf einen Blick

Der NextPDF Backport Builder ist die Build-Infrastruktur, die eine zurückportierte Distribution des NextPDF-Ökosystems für PHP-Laufzeiten erzeugt, die unterhalb der Entwicklungs-Baseline liegen. NextPDF selbst wird für eine moderne PHP-Version entwickelt und verwendet Syntax, die ältere Interpreter ablehnen. Der Builder verarbeitet den Quellcode mit Rector, einer Transformations-Engine für abstrakte Syntaxbäume, und gibt Pakete aus, deren Syntax von einer PHP-8.1- oder PHP-7.4-Laufzeit akzeptiert wird.

Der Composer-Paketname lautet nextpdf/backport-builder. Das Paket deklariert "type": "project" und enthält keine NextPDF-Laufzeitabhängigkeit. Seine einzigen Anforderungen sind die Build-Engine (rector/rector), die statische Analyse (phpstan/phpstan), der Test-Runner (phpunit/phpunit) und mehrere symfony/polyfill-*-Pakete, die in der erzeugten Ausgabe verwendet werden. Dies wurde anhand von composer.json im Wurzelverzeichnis des Repositorys verifiziert.

Was dieses Paket nicht ist

Dieses Repository enthält die NextPDF-Engine nicht. Es enthält die Regeln und Skripte, die die Engine in eine zurückportierte Form transformieren. Daraus ergeben sich drei klare Abgrenzungen:

• Sie installieren dies nicht, um PDFs zu rendern. Das Artefakt, das Sie installieren, ist nextpdf/backport; es wird von diesem Builder erzeugt. Der Builder verbleibt auf dem Maintainer- oder CI-Host.
• Sie entwickeln nicht auf Basis des generierten Codes. Die generierte Distribution ist ein maschinell erzeugtes, schreibgeschütztes Artefakt. Richten Sie Fehlerberichte und Funktionswünsche an die ursprünglichen nextpdf/*-Quell-Repositories.
• Die Ausgabe wird als Versions-Tags ausgeliefert, nicht als Branches dieses Repositorys. Die Release-Pipeline versieht den generierten Baum mit einem Tag und hängt Archive an ein GitHub-Release an.

Was er erzeugt

Der Builder gibt Composer-Pakete aus, deren Namen und Lizenzen in scripts/adjust-composer.php festgelegt sind:

Erzeugtes Paket	Lizenz	Geltungsbereich	Erstellt wann
nextpdf/backport	Apache-2.0	Core sowie Framework-Adapter und die tcpdf-Kompatibilitätsschicht für das PHP-8.1-Ziel	Immer
nextpdf/backport-pro	proprietary	Das Pro-Modul, ausgegeben als separates Paket	PHP-8.1-Ziel, wenn Pro-Quellcode vorhanden ist und Pro nicht ausgeschlossen wird

Das Paket nextpdf/backport deklariert Composer-replace-Einträge, sodass es nach der Installation die ursprünglichen Paket-Constraints erfüllt. Für das PHP-8.1-Ziel sind die ersetzten Pakete nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter und nextpdf/compat-legacy. Für das PHP-7.4-Ziel wird nur nextpdf/core ersetzt, da der PHP-7.4-Build core-only ist. Dies wurde anhand von scripts/adjust-composer.php (buildReplace()) verifiziert.

Der Autoloader einer konsumierenden Anwendung löst den zusammengeführten Codebaum über ein einziges PSR-4-Präfix auf, NextPDF\, das auf src/ abgebildet wird. PSR-4 bildet ein Namespace-Präfix auf ein Basisverzeichnis ab und löst jeden vollständig qualifizierten Klassennamen zu einer darunterliegenden Datei auf – siehe PHP-FIG PSR-4. Das Pro-Paket bildet NextPDF\Pro\ auf sein eigenes src/ ab.

Unterstützte PHP-Matrix

Die folgende Matrix gibt nur an, was die Rector-Konfigurationen und die Build-Skripte erzwingen. Der Build-Host führt stets ein modernes PHP aus. Die Ausgabe zielt auf eine ältere Version ab.

Aspekt	Wert	Nachweis
PHP des Build-Hosts	>=8.4 <9.0	composer.jsonrequire.php
CI-Build-/Test-PHP	8.5	.github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5')
PHP-8.1-Ziel – Ausgabe-Constraint	>=8.1 <8.5	scripts/adjust-composer.php (generatePublicComposer())
PHP-7.4-Ziel – Ausgabe-Constraint	>=7.4 <8.1	scripts/adjust-composer.php (generatePublicComposer())
PHP-8.1-Ziel – Geltungsbereich	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, separat)	scripts/merge-sources.php, scripts/adjust-composer.php
PHP-7.4-Ziel – Geltungsbereich	Nur Core	scripts/build.php (--target=php74 erzwingt core-only, Pro deaktiviert)

Der PHP-8.1-Build wird auf PHP 8.1, 8.2, 8.3 und 8.4 validiert. Der PHP-7.4-Build wird auf PHP 7.4 und 8.0 validiert. Dies wurde anhand der Job-Matrizen validate-php81 und validate-php74 in .github/workflows/build.yml verifiziert. Diese Laufzeiten durchläuft die Pipeline. Sie bilden ein beobachtetes Validierungsset, keine Konformitätsaussage.

Das Dual-Branch-Modell

Dieses Repository hat keinen main-Branch. PHP74 ist der Standard-Branch und PHP81 ist der zweite permanente Branch. Der Branch, auf dem Sie sich befinden, bestimmt zwei Dinge: das Ziel, auf das der lokale Build standardmäßig ausgerichtet ist, und die Quellen, die zusammengeführt werden. Eine Änderung, die beide Ziele betrifft, wird über einen eigenen Pull Request auf jeden Branch angewendet. Der Continuous-Integration-Workflow läuft sowohl auf PHP74 als auch auf PHP81. Dies wurde anhand von git branch -a und .github/workflows/0-ci.yml (branches: [PHP74, PHP81]) verifiziert.

Wie ein Release zustande kommt

Der Release-Ablauf ist ereignisgesteuert. Wenn die NextPDF-Quellorganisation einen Release-Tag veröffentlicht, löst ein Repository-Dispatch-Ereignis vom Typ source-release den Build-Workflow aus. Der Workflow checkt jedes Quell-Repository mit dem passenden Tag aus, führt die Pipeline aus, prüft die Ausgabe auf der Ziellaufzeit auf Syntaxfehler, validiert sie über die Support-Matrix und hängt die Archive an ein GitHub-Release an. Der Versions-Tag folgt der semantischen Versionierung – eine Versionsnummer ist MAJOR.MINOR.PATCH für eine deklarierte öffentliche API (Semantic Versioning 2.0.0 §2). Dies wurde anhand von .github/workflows/build.yml verifiziert.

Wie es weitergeht

• /integrations/backport/install/ – wie Sie den Builder auf einem Build-Host beziehen und wie eine konsumierende Anwendung das erzeugte Paket installiert.
• /integrations/backport/configuration/ – die Rector-Konfigurationen, benutzerdefinierten Regeln und Build-Flags.
• /integrations/backport/quickstart/ – ein ausführbarer Probelauf und ein vollständiger quellbasierter Build-Aufruf.
• /integrations/backport/production-usage/ – wie Sie den Builder in einen Release-Workflow einbinden.
• /integrations/backport/troubleshooting/ – die Fehlerzustände, vor denen die Pipeline schützt, und wie sie zu interpretieren sind.
• /integrations/backport/security-and-operations/ – die Haltung zur Lieferkette, die Vertrauensgrenze und betriebliche Garantien.
• /integrations/backport/boot-and-discovery/ – wie der Builder Quellmodule erkennt und bootet.
• /integrations/backport/integration/ – der Integrationsvertrag für den Build-Host.