Zum Inhalt springen
NextPDF
getnextpdf.com

Pro Edition

NextPDF Pro Schnellstart

Auf einen Blick

Abschnitt betitelt „Auf einen Blick“

Sie haben ein NextPDF-Pro-Lizenz-Envelope. Dieses Tutorial verwandelt es in vier kurzen Schritten in ein erstes verifiziertes Ergebnis. Sie installieren nextpdf/pro aus dem privaten Repository, aktivieren Ihre Lizenz, bestätigen die von der Laufzeit aufgelöste Berechtigung, rendern dann ein vorlagenbasiertes PDF und signieren es. Jeder Schritt zeigt die Ausgabe, die Sie sehen sollten.

Diese Funktion wird in NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Voraussetzungen

Abschnitt betitelt „Voraussetzungen“
  • PHP 8.4 und Composer 2. Die Premium-Pakete erfordern PHP >=8.4 <9.0.
  • Zugangsdaten für das private Repository. Ihr Portal stellt eine Repository-URL, einen Benutzernamen und ein Token aus. Die Einrichtung ist unter Installieren und authentifizieren beschrieben.
  • Ihr Lizenz-Envelope. Melden Sie sich in Ihrem Konto unter app.getnextpdf.com an, unterzeichnen Sie die Lizenzvereinbarung und laden Sie das signierte Envelope für Ihre Bereitstellung herunter. Behandeln Sie es wie einen API-Schlüssel.
  • ionCube Loader (nur codierte Builds). Der Pro-Trial und der kostenpflichtige, ionCube-codierte Pro-Build benötigen den Loader für PHP 8.4 — siehe ionCube-Einrichtung.

1. Installieren und aktivieren

Abschnitt betitelt „1. Installieren und aktivieren“

Richten Sie Composer auf Ihr privates Repository aus, authentifizieren Sie sich und binden Sie das Paket ein:

Terminal-Fenster
composer config repositories.nextpdf composer https://repo.example.com/nextpdf
composer config --auth http-basic.repo.example.com your-username your-token
composer require nextpdf/pro:^3

Ersetzen Sie die Repository-URL und die Zugangsdaten durch die aus Ihrem Portal. Alle drei Authentifizierungsmethoden (Projekt-auth.json, COMPOSER_AUTH, globale Authentifizierung) sind unter Installieren und authentifizieren beschrieben.

Legen Sie als Nächstes das signierte Lizenz-Envelope dort ab, wo Ihre Bereitstellung es lädt, gemäß Ihrer Konfigurationskonvention, und führen Sie den Aktivierungsschritt Ihrer Integration aus — die meisten Frameworks stellen ihn als Konsolenbefehl bereit. Unter der Haube ist die Online-Aktivierung ein einziger Aufruf auf der Lizenzierungsfläche:

public function activate(string $licenseJws, string $deploymentId, ?string $machineFingerprintHash = null, ?string $expectedLicenseId = null, ?string $clientNonce = null): StatusResponse

Wirft oder schlägt fehl mit: NextPDF\Enterprise\Licensing\LicenseClientException bei einem Transportfehler, einem Nicht-200-Status oder einer fehlerhaft gelieferten Nonce, und NextPDF\Accelerator\Exception\SpectrumAuthenticationException bei jedem Fehlschlag der signierten Statusverifizierung. Auf dem ionCube-Kanal verifiziert sich die Lizenz zusätzlich periodisch online; der Signed-Source-Kanal verifiziert lokal — siehe Zwei Auslieferungskanäle.

2. Ihre Berechtigung verifizieren

Abschnitt betitelt „2. Ihre Berechtigung verifizieren“

Fragen Sie den Berechtigungs-Evaluator — die alleinige Autorität für Lizenzentscheidungen — was Ihr Envelope aufgelöst hat. $license ist der verifizierte NextPDF\Enterprise\Licensing\LicenseKey, den der Lizenzierungs-Bootstrap Ihrer Integration bereitstellt; null zeigt das fail-closed-Ergebnis ohne Lizenz.

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;


$result = (new EntitlementEvaluator())->evaluate($license);


printf("status:   %s\n", $result->status->value);
printf("edition:  %s\n", $result->edition?->value ?? '(none)');
printf("channel:  %s\n", $result->channel->value);
printf("branding: %s\n", $result->brandingMode->value);
printf("runtime:  %s\n", $result->runtimeAllowed ? 'allowed' : 'disabled');

Die dahinterstehende Methode (sie wirft nicht):

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

Mit einer aktiven, kostenpflichtigen Pro-Lizenz erwarten Sie:

status:   active
edition:  pro
channel:  paid
branding: none
runtime:  allowed

Bei einer Trial- oder Evaluierungslizenz erwarten Sie stattdessen channel: evaluation und branding: evaluation. Jede Pro-Funktion läuft weiterhin, und die gerenderte Ausgabe trägt konstruktionsbedingt ein sichtbares Evaluierungs-Wasserzeichen. Eine kostenpflichtige Lizenz entfernt es ohne Codeänderung — siehe Trial- und Evaluierungs-Branding.

3. Erstes Ergebnis

Abschnitt betitelt „3. Erstes Ergebnis“

Nun der spannende Teil: eine JSON-Vorlage parsen, Ihre Daten mit typbewusster Formatierung binden, die gebundenen Werte rendern und das Dokument signieren. Speichern Sie dies als quickstart.php neben Ihrem vendor/-Verzeichnis und führen Sie php quickstart.php aus. Sie benötigen ein Signaturzertifikat als PKCS#12-Datei (signing-cert.p12); ein selbstsigniertes ist für dieses Tutorial ausreichend. Für die Signatur in Produktion sind ein ordnungsgemäß geschützter privater Schlüssel, eine echte Zertifikatskette und eine von Ihren Empfängern akzeptierte Trust-Policy erforderlich — selbstsignierte Signaturen sind für vertrauenswürdige Empfänger-Workflows nicht geeignet.

<?php


declare(strict_types=1);


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


use NextPDF\Core\Document;
use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;


// Parse a JSON template: one A4 page, three positioned placeholders.
$template = (new TemplateParser())->parse(<<<'JSON'
{
    "name": "welcome-letter",
    "pageSize": "A4",
    "orientation": "P",
    "placeholders": [
        {"name": "customer", "type": "text",     "x": 25, "y": 60, "width": 160, "height": 10},
        {"name": "issued",   "type": "date",     "x": 25, "y": 72, "width": 80,  "height": 10},
        {"name": "total",    "type": "currency", "x": 25, "y": 84, "width": 80,  "height": 10, "format": "EUR "}
    ]
}
JSON);


// Bind data. Keys match placeholder names case-insensitively.
$binding = (new TemplateDataBinder())->bind($template, [
    'customer' => 'Aurora Paper Co.',
    'issued'   => '2026-07-03',
    'total'    => 1249.5,
]);


printf(
    "Bound %d of %d placeholders (%d missing, %d warnings)\n",
    $binding->count(),
    count($template->placeholders),
    count($binding->missingFields),
    count($binding->warnings),
);


// Render the bound values with the Core document API.
$doc = Document::createStandalone();
$doc->setTitle('Welcome letter');
$doc->addPage();
$doc->setFont('helvetica', '', 12);


foreach ($binding->bindings as $bound) {
    $doc->text($bound->placeholder->x, $bound->placeholder->y, $bound->formattedValue);
}


// Apply a PAdES B-B baseline signature, then save once.
$doc->setSignature(
    CertificateInfo::fromPkcs12(__DIR__ . '/signing-cert.p12', (string) getenv('NEXTPDF_P12_PASSWORD')),
    SignatureLevel::PAdES_B_B,
);


$doc->save(__DIR__ . '/welcome-letter-signed.pdf');


echo "Created: welcome-letter-signed.pdf\n";

Erwartete Ausgabe:

Bound 3 of 3 placeholders (0 missing, 0 warnings)
Created: welcome-letter-signed.pdf

Öffnen Sie welcome-letter-signed.pdf in einem PDF-Reader: Die drei gebundenen Werte erscheinen an ihren Vorlagenpositionen (issued formatiert als Y-m-d, total als EUR 1,249.50), und das Signaturpanel des Readers zeigt eine Signatur. Die ausgegebene Struktur folgt dem PAdES-Baseline-Profil B-B; NextPDF dokumentiert dies als Funktion, nicht als Zertifizierung — Umfang und Konformitätshaltung finden Sie auf der Seite zu den PAdES-Stufen. Wenn das Vorlagen-JSON fehlerhaft ist, wirft TemplateParser::parse() eine InvalidArgumentException mit einer Meldung mit dem Präfix Template validation failed:.

Die soeben verwendeten Schlüsselsignaturen, wörtlich:

public function parse(string $json): TemplateDefinition
public function bind(TemplateDefinition $template, array $data): BindingResult
public static function fromPkcs12(string $p12Path, #[SensitiveParameter] string $password = ''): self
public function setSignature(CertificateInfo $certInfo, SignatureLevel $level = SignatureLevel::PAdES_B_B, ?TsaClient $tsaClient = null, ?ClientInterface $httpClient = null): static
public function save(string $path): void

Wirft oder schlägt fehl mit: parse() — InvalidArgumentException, wenn das JSON ungültig ist oder nicht der erwarteten Struktur entspricht; fromPkcs12() — NextPDF\Exception\SignatureException, wenn die Datei nicht gelesen oder geparst werden kann; setSignature() — NextPDF\Exception\InvalidConfigException, wenn die Linearisierung bereits aktiviert ist (PAdES und Fast Web View schließen sich gegenseitig aus); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException oder NextPDF\Exception\CompressionException, wenn die Datei nicht geschrieben werden kann. bind() wirft nicht; es meldet stattdessen missingFields und warnings.

4. Wenn etwas fehlschlägt

Abschnitt betitelt „4. Wenn etwas fehlschlägt“

Composer findet oder lädt nextpdf/pro nicht

Abschnitt betitelt „Composer findet oder lädt nextpdf/pro nicht“

Ein 401/403 während composer require oder „could not be found” bedeutet, dass das private Repository oder seine Zugangsdaten für dieses Projekt nicht konfiguriert sind. Der Host-Schlüssel in auth.json muss exakt mit dem Host der Repository-URL übereinstimmen. Arbeiten Sie Installieren und authentifizieren durch.

Die Laufzeit meldet keine Lizenz

Abschnitt betitelt „Die Laufzeit meldet keine Lizenz“

Schritt 2 gibt status: no_license, runtime: disabled und die Warnung des Evaluators aus — die rohe Premium-Laufzeitmeldung (von beiden Editionen gemeinsam genutzt) lautet: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Premium-Funktionen schlagen ohne verifiziertes Envelope fail-closed fehl. Eine vorhandene, aber beschädigte Envelope-Datei wird niemals als fehlend behandelt — sie löst NextPDF\Enterprise\Licensing\Storage\LicenseStorageException mit Meldungen wie License file is present but unreadable: ... oder License file is present but empty: ... aus. Legen Sie das Envelope am konfigurierten Pfad ab und machen Sie es für den Benutzer des PHP-Prozesses lesbar.

Das Signaturzertifikat lädt nicht

Abschnitt betitelt „Das Signaturzertifikat lädt nicht“

CertificateInfo::fromPkcs12() wirft NextPDF\Exception\SignatureException, wenn die .p12-Datei nicht gelesen oder geparst werden kann. Die üblichen Ursachen sind ein falscher Pfad, ein falsches Passwort (prüfen Sie NEXTPDF_P12_PASSWORD) oder eine Datei, die nicht tatsächlich PKCS#12 ist. Überprüfen Sie dies mit openssl pkcs12 -info -in signing-cert.p12 -noout.

Wie es weitergeht

Abschnitt betitelt „Wie es weitergeht“