Ga naar inhoud
NextPDF
getnextpdf.com

Pro editie

NextPDF Pro snelstart

In één oogopslag

Sectie met titel “In één oogopslag”

Je hebt een NextPDF Pro licentie-envelop. Deze tutorial maakt daar in vier korte stappen een eerste geverifieerd resultaat van. Je installeert nextpdf/pro uit de private repository, activeert je licentie, bevestigt het entitlement dat de runtime heeft opgelost, en rendert vervolgens een op een template gebaseerde PDF die je ondertekent. Elke stap laat de uitvoer zien die je zou moeten zien.

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een Pro-tier licentie-envelop. Een deployment zonder dat entitlement laadt de klassen van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Vereisten

Sectie met titel “Vereisten”
  • PHP 8.4 en Composer 2. De premium-pakketten vereisen PHP >=8.4 <9.0.
  • Private-repositorygegevens. Je portaal geeft een repository-URL, gebruikersnaam en token uit. De setup wordt behandeld in Installeren en authenticeren.
  • Je licentie-envelop. Meld je aan bij je account op app.getnextpdf.com, onderteken de licentieovereenkomst en download de ondertekende envelop voor je deployment. Behandel het als een API-sleutel.
  • ionCube Loader (alleen gecodeerde builds). De Pro-trial en de betaalde, ionCube-gecodeerde Pro-build hebben de Loader voor PHP 8.4 nodig — zie ionCube-setup.

1. Installeren en activeren

Sectie met titel “1. Installeren en activeren”

Wijs Composer naar je private repository, authenticeer en require het pakket:

Terminal window
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

Vervang de repository-URL en gegevens door die uit je portaal. Alle drie de authenticatiemethoden (project-auth.json, COMPOSER_AUTH, globale auth) worden beschreven in Installeren en authenticeren.

Plaats vervolgens de ondertekende licentie-envelop waar je deployment hem laadt, volgens je configuratieconventie, en voer de activatiestap van je integratie uit — de meeste frameworks stellen die beschikbaar als een consolecommando. Onder de motorkap is online activatie één aanroep op het licensing-oppervlak:

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

Gooit of faalt met: NextPDF\Enterprise\Licensing\LicenseClientException bij een transportfout, een niet-200-status of een verkeerd meegegeven nonce, en NextPDF\Accelerator\Exception\SpectrumAuthenticationException bij elke ondertekende-status-verificatiefout. Op het ionCube-kanaal verifieert de licentie ook periodiek online; het signed-source-kanaal verifieert lokaal — zie Twee leveringskanalen.

2. Verifieer je entitlement

Sectie met titel “2. Verifieer je entitlement”

Vraag de entitlement-evaluator — de enige autoriteit voor licentiebeslissingen — waartoe je envelop is opgelost. $license is de geverifieerde NextPDF\Enterprise\Licensing\LicenseKey die de licensing-bootstrap van je integratie beschikbaar stelt; null toont het fail-closed geen-licentie-resultaat.

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

De methode erachter (die gooit niet):

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

Met een actieve betaalde Pro-licentie verwacht je:

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

Bij een trial- of evaluatietoekenning verwacht je in plaats daarvan channel: evaluation en branding: evaluation. Elke Pro-mogelijkheid draait nog steeds, en de gerenderde uitvoer draagt bewust een zichtbaar evaluatie-watermerk. Een betaalde licentie verwijdert het zonder codewijziging — zie Trial- en evaluatiebranding.

3. Eerste resultaat

Sectie met titel “3. Eerste resultaat”

Nu het leuke deel: parse een JSON-template, bind je data met type-bewuste formattering, render de gebonden waarden en onderteken het document. Sla dit op als quickstart.php naast je vendor/-directory en voer php quickstart.php uit. Je hebt een ondertekencertificaat nodig als PKCS#12-bestand (signing-cert.p12); een zelfondertekend bestand is prima voor deze tutorial. Productie-ondertekening vereist een goed beschermde private sleutel, een echte certificaatketen en een trust-policy die je ontvangers accepteren — zelfondertekende handtekeningen zijn niet geschikt voor vertrouwde ontvangers-workflows.

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

Verwachte uitvoer:

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

Open welcome-letter-signed.pdf in een PDF-lezer: de drie gebonden waarden verschijnen op hun templateposities (issued geformatteerd als Y-m-d, total als EUR 1,249.50), en het handtekeningpaneel van de lezer toont één handtekening. De uitgestoten structuur volgt het PAdES baseline B-B-profiel; NextPDF documenteert dit als een mogelijkheid, niet als een certificering — de scope en conformiteitshouding staan op de PAdES-niveaupagina. Als de template-JSON ongeldig is, gooit TemplateParser::parse() een InvalidArgumentException met een bericht met het voorvoegsel Template validation failed:.

De belangrijkste signatures die je zojuist hebt gebruikt, verbatim:

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

Gooit of faalt met: parse() — InvalidArgumentException wanneer de JSON ongeldig is of niet voldoet aan de verwachte structuur; fromPkcs12() — NextPDF\Exception\SignatureException wanneer het bestand niet gelezen of geparsed kan worden; setSignature() — NextPDF\Exception\InvalidConfigException wanneer linearisatie al is ingeschakeld (PAdES en Fast Web View sluiten elkaar wederzijds uit); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException, of NextPDF\Exception\CompressionException wanneer het bestand niet geschreven kan worden. bind() gooit niet; het rapporteert in plaats daarvan missingFields en warnings.

4. Wanneer er iets faalt

Sectie met titel “4. Wanneer er iets faalt”

Composer kan nextpdf/pro niet vinden of ophalen

Sectie met titel “Composer kan nextpdf/pro niet vinden of ophalen”

Een 401/403 tijdens composer require, of “could not be found”, betekent dat de private repository of de bijbehorende gegevens niet zijn geconfigureerd voor dit project. De host-sleutel in auth.json moet exact overeenkomen met de host van de repository-URL. Werk Installeren en authenticeren door.

De runtime meldt geen licentie

Sectie met titel “De runtime meldt geen licentie”

Stap 2 print status: no_license, runtime: disabled, en de waarschuwing van de evaluator — het ruwe premium-runtime-bericht (gedeeld door beide edities) is: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Premium-features falen gesloten zonder een geverifieerde envelop. Een aanwezig-maar-kapot envelopbestand wordt nooit als afwezig behandeld — het werpt NextPDF\Enterprise\Licensing\Storage\LicenseStorageException met berichten zoals License file is present but unreadable: ... of License file is present but empty: .... Plaats de envelop op het geconfigureerde pad en maak het leesbaar voor de gebruiker van het PHP-proces.

Het ondertekencertificaat laadt niet

Sectie met titel “Het ondertekencertificaat laadt niet”

CertificateInfo::fromPkcs12() gooit NextPDF\Exception\SignatureException wanneer het .p12-bestand niet gelezen of geparsed kan worden. De gebruikelijke oorzaken zijn een verkeerd pad, een verkeerd wachtwoord (controleer NEXTPDF_P12_PASSWORD), of een bestand dat niet daadwerkelijk PKCS#12 is. Verifieer met openssl pkcs12 -info -in signing-cert.p12 -noout.

Waar je hierna heen kunt

Sectie met titel “Waar je hierna heen kunt”