Szybki start z NextPDF Pro

W skrócie

Masz kopertę licencyjną NextPDF Pro. Ten samouczek zamienia ją w pierwszy zweryfikowany wynik w czterech krótkich krokach. Instalujesz nextpdf/pro z prywatnego repozytorium, aktywujesz licencję, potwierdzasz uprawnienie rozpoznane przez środowisko wykonawcze, a następnie renderujesz PDF z szablonu i podpisujesz go. Każdy krok pokazuje wynik, który powinieneś zobaczyć.

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się za pomocą koperty licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Wymagania wstępne

• PHP 8.4 i Composer 2. Pakiety premium wymagają PHP >=8.4 <9.0.
• Poświadczenia prywatnego repozytorium. Portal wydaje adres URL repozytorium, nazwę użytkownika i token. Konfiguracja została omówiona w Instalacja i uwierzytelnianie.
• Koperta licencyjna. Zaloguj się na konto w app.getnextpdf.com, podpisz umowę licencyjną i pobierz podpisaną kopertę dla swojego wdrożenia. Traktuj ją jak klucz API.
• ionCube Loader (tylko buildy zakodowane). Wersja próbna Pro oraz płatny, zakodowany ionCube build Pro wymagają Loadera dla PHP 8.4 — zobacz Konfiguracja ionCube.

1. Instalacja i aktywacja

Skieruj Composer na prywatne repozytorium, uwierzytelnij się i dodaj pakiet:

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

Podstaw adres URL repozytorium i poświadczenia z portalu. Wszystkie trzy metody uwierzytelniania (projektowy auth.json, COMPOSER_AUTH, uwierzytelnianie globalne) są opisane w Instalacja i uwierzytelnianie.

Następnie umieść podpisaną kopertę licencyjną tam, gdzie ładuje ją Twoje wdrożenie, zgodnie z Twoją konwencją konfiguracji, i uruchom krok aktywacji swojej integracji — większość frameworków udostępnia go jako polecenie konsolowe. Pod maską aktywacja online to jedno wywołanie na warstwie licencjonowania:

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

Zgłasza wyjątek lub kończy się niepowodzeniem z: NextPDF\Enterprise\Licensing\LicenseClientException przy błędzie transportu, statusie innym niż 200 lub błędnie dostarczonym nonce, oraz NextPDF\Accelerator\Exception\SpectrumAuthenticationException przy dowolnym niepowodzeniu weryfikacji podpisanego statusu. Na kanale ionCube licencja jest również okresowo weryfikowana online; kanał signed-source weryfikuje lokalnie — zobacz Dwa kanały dostawy.

2. Weryfikacja uprawnienia

Zapytaj ewaluator uprawnień — jedyny autorytet w kwestii decyzji licencyjnych — do czego rozpoznała się Twoja koperta. $license to zweryfikowany NextPDF\Enterprise\Licensing\LicenseKey, który udostępnia bootstrap licencjonowania Twojej integracji; null pokazuje wynik fail-closed oznaczający brak licencji.

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');

Metoda, która za tym stoi (nie zgłasza wyjątku):

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

Przy aktywnej płatnej licencji Pro spodziewaj się:

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

Przy nadaniu próbnym lub ewaluacyjnym spodziewaj się zamiast tego channel: evaluation i branding: evaluation. Każda funkcja Pro nadal działa, a wyrenderowany wynik z założenia zawiera widoczny znak wodny ewaluacji. Płatna licencja usuwa go bez żadnej zmiany w kodzie — zobacz Wersja próbna i branding ewaluacji.

3. Pierwszy wynik

Teraz najprzyjemniejsza część: sparsuj szablon JSON, powiąż swoje dane z formatowaniem uwzględniającym typy, wyrenderuj powiązane wartości i podpisz dokument. Zapisz to jako quickstart.php obok katalogu vendor/ i uruchom php quickstart.php. Potrzebujesz certyfikatu podpisującego w postaci pliku PKCS#12 (signing-cert.p12); dla tego samouczka wystarczy samopodpisany. Podpisywanie produkcyjne wymaga odpowiednio chronionego klucza prywatnego, prawdziwego łańcucha certyfikatów oraz polityki zaufania akceptowanej przez odbiorców — podpisy samopodpisane nie nadają się do zaufanych przepływów pracy z odbiorcami.

<?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";

Oczekiwany wynik:

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

Otwórz welcome-letter-signed.pdf w czytniku PDF: trzy powiązane wartości pojawiają się na pozycjach z szablonu (issued sformatowane Y-m-d, total jako EUR 1,249.50), a panel podpisu czytnika pokazuje jeden podpis. Wyemitowana struktura jest zgodna z podstawowym profilem PAdES B-B; NextPDF dokumentuje to jako funkcję, a nie certyfikację — zakres i postawa zgodności znajdują się na stronie poziomów PAdES. Jeśli szablon JSON jest nieprawidłowy, TemplateParser::parse() zgłasza InvalidArgumentException z komunikatem poprzedzonym Template validation failed:.

Kluczowe sygnatury, których właśnie użyłeś, dosłownie:

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

Zgłasza wyjątek lub kończy się niepowodzeniem z: parse() — InvalidArgumentException, gdy JSON jest nieprawidłowy lub nie odpowiada oczekiwanej strukturze; fromPkcs12() — NextPDF\Exception\SignatureException, gdy pliku nie można odczytać ani sparsować; setSignature() — NextPDF\Exception\InvalidConfigException, gdy linearyzacja jest już włączona (PAdES i Fast Web View wzajemnie się wykluczają); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException lub NextPDF\Exception\CompressionException, gdy pliku nie można zapisać. bind() nie zgłasza wyjątku; zamiast tego raportuje missingFields i warnings.

4. Gdy coś zawiedzie

Composer nie może znaleźć ani pobrać nextpdf/pro

Błąd 401/403 podczas composer require lub komunikat “could not be found” oznacza, że prywatne repozytorium lub jego poświadczenia nie są skonfigurowane dla tego projektu. Klucz hosta w auth.json musi dokładnie odpowiadać hostowi z adresu URL repozytorium. Przejdź przez Instalacja i uwierzytelnianie.

Środowisko wykonawcze zgłasza brak licencji

Krok 2 wypisuje status: no_license, runtime: disabled oraz ostrzeżenie ewaluatora — surowy komunikat środowiska premium (wspólny dla obu edycji) to: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Funkcje premium kończą się niepowodzeniem fail-closed bez zweryfikowanej koperty. Obecny, ale uszkodzony plik koperty nigdy nie jest traktowany jako nieobecny — zgłasza NextPDF\Enterprise\Licensing\Storage\LicenseStorageException z komunikatami takimi jak License file is present but unreadable: ... lub License file is present but empty: .... Umieść kopertę w skonfigurowanej ścieżce i uczyń ją możliwą do odczytu przez użytkownika procesu PHP.

Certyfikat podpisujący się nie ładuje

CertificateInfo::fromPkcs12() zgłasza NextPDF\Exception\SignatureException, gdy pliku .p12 nie można odczytać ani sparsować. Zwykłe przyczyny to błędna ścieżka, błędne hasło (sprawdź NEXTPDF_P12_PASSWORD) lub plik, który nie jest w rzeczywistości PKCS#12. Zweryfikuj poleceniem openssl pkcs12 -info -in signing-cert.p12 -noout.

Dokąd dalej

• Szablon — pełna definicja szablonu i dokumentacja wiązania.
• Podpisz PDF za pomocą PAdES B-B, a następnie rozszerz do PAdES B-T — dodaj do podpisu znacznik czasu RFC 3161.
• Funkcje NextPDF Pro — wszystko, co obejmuje Twoja licencja Pro.
• Dwa kanały dostawy — dzierżawa online ionCube kontra w pełni offline signed source.
• Wersja próbna i branding ewaluacji — jak wygląda znak wodny ewaluacji i jak płatna licencja go usuwa.