NextPDF-FAQ

Auf einen Blick

Diese Seite beantwortet die Fragen, die zuerst aufkommen, wenn Sie NextPDF evaluieren oder ein neues Projekt beginnen. Jede Antwort ist kurz und verlinkt auf die Seite, die sie vollständig behandelt. NextPDF ist eine PHP-8.4-Engine, die Dokumente im Portable Document Format (PDF) 2.0 erzeugt und inspiziert – das von ISO 32000-2 definierte Dateiformat.

Wenn Sie ganz neu sind, lesen Sie zuerst Erste Schritte und kommen Sie dann hierher zurück für die Einzelheiten.

Erste Schritte

Welche Edition brauche ich: Core, Pro oder Enterprise?

Beginnen Sie mit Core. Der Open-Source-Kern (nextpdf/core) erzeugt PDF-Ausgaben, rendert unterstütztes HTML in PDFs und inspiziert PDFs unter der Apache-2.0-Lizenz und kostenlos. Core erzeugt bereits CMS-SignedData-Signaturen für die Baseline-Stufen B-B und B-T der PDF Advanced Electronic Signatures (PAdES). Wählen Sie Pro, wenn Sie erweiterte Generierung und Dokumentoperationen, elektronische Rechnungsausgaben (Factur-X / ZUGFeRD) oder fortgeschrittene Signier-Workflows wie Remote-, Cloud-KMS- und sequenzielles Signieren benötigen. Wählen Sie Enterprise, wenn Sie PDF/A-Archivierungs-Authoring-Workflows, die PAdES-Langzeitstufen (B-LT / B-LTA) mit einem Document Security Store und Dokument-Zeitstempeln, hardwaregestütztes Signieren über ein Hardware-Sicherheitsmodul (HSM) oder qualifizierte elektronische Signaturen benötigen. Pro und Enterprise sind die beiden lizenzierten Editionen von NextPDF Premium, der bezahlten Produktlinie; siehe Wählen Sie Ihren Weg.

Ist es wirklich Apache-2.0?

Ja, für den Kern. nextpdf/core deklariert "license": "Apache-2.0" und liefert den vollständigen Text der Apache License 2.0 in seiner LICENSE-Datei aus. Sie dürfen den Kern verwenden, modifizieren, weiterverbreiten und kommerzialisieren, vorbehaltlich der Attributions- und NOTICE-Anforderungen (Apache-2.0 §4). NextPDF Pro und NextPDF Enterprise sind proprietäre kommerzielle Editionen und sind nicht von dieser Lizenz abgedeckt. Der Name und das Logo von NextPDF sind Marken, getrennt von der Code-Lizenz. Siehe Produktlizenzierung.

Was ist die minimale PHP-Version?

PHP 8.4. Der Paket-Constraint lautet >=8.4 <9.0, sodass Composer die Installation auf PHP 8.3 oder darunter oder auf PHP 9 verweigert. NextPDF ist auf eine moderne Laufzeit ausgelegt und nutzt deren Sprachfunktionen direkt. Siehe NextPDF installieren.

Benötigt es eine externe Binärdatei oder einen Headless-Browser?

Nein, nicht für die Core-Engine. Die native Engine ist in PHP und in Standard-PHP-Erweiterungen implementiert, ohne externe PDF-Binärdatei und ohne verpflichtenden Headless-Browser: Die fluente API und die eingebaute writeHtml()-HTML-Pipeline laufen prozessintern ohne Browser und ohne Netzwerkaufruf. Eine Chrome- oder Chromium-Binärdatei ist optional und wird nur für den Artisan-Renderer (writeHtmlChrome()) benötigt, den Sie separat als nextpdf/artisan installieren. Die Cloudflare- und Gotenberg-Bridges sind ebenfalls optional und rufen einen Dienst auf. Siehe Wählen Sie Ihren Weg.

Welche PHP-Erweiterungen benötigt es?

Die composer.json des Kerns erfordert die Standard-Erweiterungen ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl und ext-openssl, die häufig verfügbare PHP-Erweiterungen sind; stellen Sie sicher, dass sie in Ihrer Laufzeit installiert und aktiviert sind. ext-curl ermöglicht die optionalen Netzwerk-Roundtrips – RFC-3161-Zeitstempelung und das Abrufen externer Assets –, sodass eine offline ablaufende native Generierung sie nicht beansprucht, Composer sie aber dennoch als harte Anforderung listet. Integrationen prüfen die von ihnen benötigten Erweiterungen beim Start und stoppen mit einer klaren Meldung, falls eine fehlt. Die vollständige Liste steht in der Paket-composer.json; siehe NextPDF installieren.

Wie erzeuge ich mein erstes PDF?

Installieren Sie den Kern und bauen Sie dann ein Dokument mit der fluenten API:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

Gehen Sie es in Ihr erstes PDF Schritt für Schritt durch.

Editionen und Lizenzierung

Hat Core irgendwelche Funktionsbeschränkungen oder ein Wasserzeichen?

Nein. Core ist die Open-Source-Engine für den Core-Funktionsumfang ohne Wasserzeichen und ohne Nag-Screen. Für den Core-Funktionsumfang – Generierung, Inspektion, Verschlüsselung, PDF/A- und PDF/UA-Ausgabe-Primitive sowie Software-Schlüssel-Signierung B-B/B-T (ohne die Premium-Workflows für Langzeitvalidierung und Schlüsselverwahrung) – ist Core vollständig. Das Evaluierungs-Wasserzeichen gilt nur für eine Premium-Evaluierungslizenz, in der Sie den vollständigen Pro- und Enterprise-Funktionsumfang hinter einer entfernbaren Markierung testen; eine bezahlte Lizenz entfernt es ohne Änderung am Anwendungscode. Siehe Lizenzierung und Aktivierung.

Benötige ich Code-Änderungen, um auf Pro oder Enterprise aufzurüsten?

Meist nicht. Wenn Sie nextpdf/premium installieren, erkennen die Framework-Integrationen und der Server es automatisch und stellen die zusätzlichen Funktionen bereit. Die meisten Anwendungen behalten dieselben übergeordneten Integrationspunkte; einige Premium-Workflows können Konfiguration oder funktionsspezifische Aufrufe erfordern. Sie aktivieren einen signierten Lizenzumschlag einmal pro Deployment. Siehe Lizenzierung und Aktivierung.

Kann ich den Kern in einem Closed-Source-Kommerzprodukt verwenden?

Ja. Die Apache License 2.0 hat keine nicht-kommerzielle Beschränkung. Sie dürfen den Kern in Closed-Source-, bezahlten oder internen kommerziellen Produkten verwenden, sofern Sie die Attributions- und NOTICE-Pflichten erfüllen und die Code-Lizenz nicht als Erlaubnis behandeln, die NextPDF-Marke zu verwenden. Siehe Produktlizenzierung und Marke und Markennutzung.

Funktionen

Kann es PDFs lesen und parsen oder nur schreiben?

Beides, mit einem Vorbehalt. NextPDF schreibt PDFs und liest sie auch: Das Inspect-Modul liest eine vorhandene Datei in ein strukturiertes InspectResult mit Komplexitäts-, Schrift-, Bild- und Risikodaten, und Sie können vorhandene Dokumente zusammenführen und aufteilen. Inspect ist als experimentell markiert, sodass sich seine Ergebnisform zwischen Minor-Versionen ändern kann – verwenden Sie es für Diagnose und Gating, nicht als langlebigen Vertrag. Siehe das Inspect-Modul.

Erzeugt es auswählbaren, durchsuchbaren Text?

Ja. Sowohl die fluente API als auch die eingebaute writeHtml()-Pipeline geben echten Textinhalt aus, keine gerasterten Bilder, sodass die Ausgabe auswählbar und durchsuchbar ist. Das writeHtmlChrome() des Artisan-Renderers hält Text ebenfalls auswählbar. Siehe Ihr erstes PDF.

Wie funktioniert das HTML- und CSS-Rendering?

Die Core-Engine enthält eine reine PHP-HTML-Pipeline. writeHtml() rendert ein HTML-Fragment mit einer unterstützten Teilmenge von CSS direkt in die Seite, ohne Browser und ohne Netzwerkaufruf. Wenn ein Layout volle Browser-Treue benötigt – etwa Flexbox, Grid oder Web-Fonts –, installieren Sie den Artisan-Renderer und rufen writeHtmlChrome() auf. Bevor Sie sich auf eine Eigenschaft verlassen, prüfen Sie die CSS-Support-Matrix.

Wie funktionieren Schriften?

Die eingebauten Standard-Schrift-Aliase wie Helvetica funktionieren ohne Einrichtung für einfachen WinAnsi-Text, sodass Ihr erstes Dokument keine Schriftdateien benötigt. Die eingebauten lateinischen Standardschriften eignen sich für grundlegenden WinAnsi-Text; Symbol und ZapfDingbats verwenden ihre eigenen Codierungen; um andere Schriftsysteme zu rendern, registrieren und betten Sie eine Schrift ein, deren Zeichenzuordnung und Shaping-Pfad dieses Schriftsystem unterstützen. Siehe die Schrift-Support-Matrix und das Schrift-Modul.

Unterstützt es PDF/A und Barrierefreiheit (PDF/UA)?

Ja, mit einer klaren Abgrenzung: Unterstützung für ein Profil ist keine Konformität. Der Kern liefert den Konformitäts-Diskriminator und die Tagging-Primitive aus – enableTaggedPdf() aktiviert die für PDF/UA-Workflows verwendete getaggte PDF-Strukturausgabe, und enablePdfA() wählt in Core ein PDF/A-Ausgabeprofil; die Premium-Editionen ergänzen darauf aufbauend übergeordnete Archivierungs-Authoring-Workflows und Werkzeuge (Validierung, Policy und Produktionsabläufe). NextPDF gibt die strukturellen Artefakte aus, die ein Profil erfordert; ein unabhängiger Validator wie veraPDF entscheidet, ob eine gegebene Datei tatsächlich konform ist. Siehe Konformität und das Barrierefreiheits-Modul.

Wie signiere ich ein PDF?

Der Kern kann Signaturen vom Typ Cryptographic Message Syntax (CMS) SignedData erzeugen und RFC-3161-Zeitstempel anwenden (die B-T-Stufe), unter Verwendung unterstützter Software-Schlüssel-Algorithmen über den konfigurierten Signierprovider. Ihr Code hängt vom Vertrag SignerInterface ab, sodass derselbe Aufruf editionsübergreifend funktioniert. Die PAdES-Langzeitstufen B-LT und B-LTA, HSM- und PKCS#11-Schlüsselverwahrung sowie qualifizierte Signaturen sind Enterprise-Funktionen; cloud- und KMS-gestützte Signier-Workflows sind in Pro enthalten. Core erzeugt die Baseline-Strukturen B-B und B-T. Siehe das Signier-Modul.

Produktion

Ist es worker-sicher und thread-sicher?

Ein Document ist einmalig verwendbar: Sobald Sie eines geschrieben haben, erstellen Sie eine frische Instanz für das nächste Dokument, statt es wiederzuverwenden. Damit fügt es sich natürlich in das Pro-Anfrage-, Pro-Job-Modell ein, das PHP-FPM, Queue-Worker und Frameworks verwenden – jede Arbeitseinheit baut ihr eigenes Dokument. Wenn Sie nicht vertrauenswürdige Eingaben parsen oder zusammensetzen, führen Sie diese Arbeit in einem begrenzten Worker aus und halten Sie die Ressourcen-Guards (maxFiles, maxTotalBytes, maxBytes) eng. Siehe das Dokument-Modul und das Bedrohungsmodell der Engine.

Ist die Ausgabe deterministisch?

Sie ist strukturell deterministisch, aber standardmäßig nicht bytegenau identisch. Zwei Läufe derselben Eingabe erzeugen strukturell gleiche PDFs, aber jedes trägt einen frischen Trailer und ein frisches Dokument-/ID, sodass die Bytes sich unterscheiden. Signieren und Zeitstempel fügen per Design weitere Variation pro Lauf hinzu. Richten Sie Vergleiche an struktureller Gleichheit aus oder normalisieren Sie die volatilen Felder, statt identische Bytes über Läufe hinweg zu erwarten.

Wie deploye ich es?

Checken Sie composer.lock ein, damit jeder bereitgestellte Worker dieselbe Engine-Version auflöst, und deployen Sie dann wie jede PHP-Bibliothek – die native Generierung benötigt keinen Daemon, keinen Browser und kein Netzwerk; Zeitstempelung (B-T), externe Assets oder die optionale Browser-Bridge erfordern konfigurierten Netzwerkzugriff. Wenn Nicht-PHP-Dienste die Engine benötigen, betreiben Sie NextPDF Server, der sie über Model Context Protocol (MCP), REST und gRPC bereitstellt. Platzieren Sie für Premium den signierten Lizenzumschlag dort, wo das Deployment ihn lädt, und führen Sie den einmaligen Aktivierungsschritt aus; da der Lizenzzustand zwischengespeichert wird, benötigt die normale Verarbeitung keinen Lizenzdienst, sodass Air-Gap-Deployments unterstützt werden. Siehe NextPDF installieren und Lizenzierung und Aktivierung.

Wohin wende ich mich bei einem Fehler, wenn etwas schiefgeht?

NextPDF meldet Fehler über die PHP-Exception-Klasse, nicht über einen String-Fehlercode, und kontextbewusste Exceptions enthalten strukturierte Diagnosefelder. Die Fehlerbehebungs-Wissensdatenbank ordnet häufige Signatur-, PDF/A-, PDF/UA-, Schrift-, Tagging- und Verschlüsselungsfehler ihrer Ursache und Lösung zu.