Guida rapida a NextPDF Pro

In sintesi

Si dispone di una busta di licenza NextPDF Pro. Questo tutorial la trasforma in un primo risultato verificato in quattro brevi passaggi. Si installa nextpdf/pro dal repository privato, si attiva la licenza, si conferma la titolarità risolta dal runtime, quindi si genera un PDF basato su template e lo si firma. Ogni passaggio mostra l’output che ci si deve aspettare.

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con una busta di licenza di livello Pro. Un deployment privo di tale titolarità non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Prerequisiti

• PHP 8.4 e Composer 2. I pacchetti premium richiedono PHP >=8.4 <9.0.
• Credenziali del repository privato. Il portale emette un URL del repository, un nome utente e un token. La configurazione è trattata in Installazione e autenticazione.
• La busta di licenza. Accedere al proprio account su app.getnextpdf.com, sottoscrivere il contratto di licenza e scaricare la busta firmata per il proprio deployment. Trattarla come una chiave API.
• ionCube Loader (solo build codificate). La versione di prova Pro e la build Pro a pagamento codificata con ionCube richiedono il Loader per PHP 8.4 — vedere Configurazione di ionCube.

1. Installazione e attivazione

Puntare Composer al proprio repository privato, autenticarsi e richiedere il pacchetto:

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

Sostituire l’URL del repository e le credenziali forniti dal portale. Tutti e tre i metodi di autenticazione (auth.json di progetto, COMPOSER_AUTH, autenticazione globale) sono descritti in Installazione e autenticazione.

Successivamente, collocare la busta di licenza firmata dove il deployment la carica, seguendo la propria convenzione di configurazione, ed eseguire il passaggio di attivazione dell’integrazione — la maggior parte dei framework lo espone come comando di console. Internamente, l’attivazione online è una singola chiamata sulla superficie di licenza:

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

Solleva o fallisce con: NextPDF\Enterprise\Licensing\LicenseClientException in caso di errore di trasporto, uno stato diverso da 200 o un nonce fornito non valido, e NextPDF\Accelerator\Exception\SpectrumAuthenticationException in caso di qualsiasi errore nella verifica dello stato firmato. Sul canale ionCube la licenza si verifica periodicamente anche online; il canale a sorgente firmata si verifica localmente — vedere Due canali di distribuzione.

2. Verificare la titolarità

Chiedere al valutatore di titolarità — l’unica autorità per le decisioni di licenza — a cosa si è risolta la busta. $license è la NextPDF\Enterprise\Licensing\LicenseKey verificata che il bootstrap di licenza dell’integrazione espone; null indica il risultato fail-closed di assenza di licenza.

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

Il metodo sottostante (non solleva eccezioni):

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

Con una licenza Pro a pagamento attiva, ci si aspetta:

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

Con una concessione di prova o valutazione, ci si aspetta invece channel: evaluation e branding: evaluation. Tutte le funzionalità Pro continuano comunque a funzionare, e l’output generato riporta per progettazione una filigrana di valutazione visibile. Una licenza a pagamento la rimuove senza alcuna modifica al codice — vedere Branding di prova e valutazione.

3. Primo risultato

Ora la parte divertente: analizzare un template JSON, associare i propri dati con formattazione consapevole del tipo, generare i valori associati e firmare il documento. Salvare questo come quickstart.php accanto alla directory vendor/ ed eseguire php quickstart.php. Serve un certificato di firma come file PKCS#12 (signing-cert.p12); per questo tutorial va bene uno autofirmato. La firma in produzione richiede una chiave privata adeguatamente protetta, una catena di certificati reale e una policy di attendibilità accettata dai destinatari — le firme autofirmate non sono adatte a flussi di lavoro con destinatari attendibili.

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

Output atteso:

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

Aprire welcome-letter-signed.pdf in un lettore PDF: i tre valori associati compaiono nelle rispettive posizioni del template (issued formattato Y-m-d, total come EUR 1,249.50), e il pannello delle firme del lettore mostra una firma. La struttura emessa segue il profilo di base PAdES B-B; NextPDF la documenta come funzionalità, non come certificazione — l’ambito e la postura di conformità sono nella pagina dei livelli PAdES. Se il template JSON è malformato, TemplateParser::parse() solleva InvalidArgumentException con un messaggio preceduto da Template validation failed:.

Le firme chiave appena utilizzate, 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

Solleva o fallisce con: parse() — InvalidArgumentException quando il JSON è non valido o non è conforme alla struttura attesa; fromPkcs12() — NextPDF\Exception\SignatureException quando il file non può essere letto o analizzato; setSignature() — NextPDF\Exception\InvalidConfigException quando la linearizzazione è già abilitata (PAdES e Fast Web View sono mutuamente esclusivi); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException o NextPDF\Exception\CompressionException quando il file non può essere scritto. bind() non solleva eccezioni; riporta invece missingFields e warnings.

4. Quando qualcosa fallisce

Composer non trova o non scarica nextpdf/pro

Un 401/403 durante composer require, oppure “could not be found”, significa che il repository privato o le sue credenziali non sono configurati per questo progetto. La chiave host in auth.json deve corrispondere esattamente all’host dell’URL del repository. Seguire Installazione e autenticazione.

Il runtime segnala l’assenza di licenza

Il passaggio 2 stampa status: no_license, runtime: disabled e l’avviso del valutatore — il messaggio grezzo del runtime premium (condiviso da entrambe le edizioni) è: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Le funzionalità premium falliscono in modo chiuso in assenza di una busta verificata. Un file di busta presente ma corrotto non viene mai trattato come assente — solleva NextPDF\Enterprise\Licensing\Storage\LicenseStorageException con messaggi quali License file is present but unreadable: ... o License file is present but empty: .... Collocare la busta nel percorso configurato e renderla leggibile dall’utente del processo PHP.

Il certificato di firma non viene caricato

CertificateInfo::fromPkcs12() solleva NextPDF\Exception\SignatureException quando il file .p12 non può essere letto o analizzato. Le cause abituali sono un percorso errato, una password errata (controllare NEXTPDF_P12_PASSWORD) o un file che non è effettivamente PKCS#12. Verificare con openssl pkcs12 -info -in signing-cert.p12 -noout.

Dove proseguire

• Template — il riferimento completo alla definizione del template e al binding.
• Firmare un PDF con PAdES B-B, quindi estendere a PAdES B-T — aggiungere un timestamp RFC 3161 alla propria firma.
• Funzionalità di NextPDF Pro — tutto ciò che la licenza Pro include.
• Due canali di distribuzione — lease online ionCube rispetto a sorgente firmata completamente offline.
• Branding di prova e valutazione — l’aspetto della filigrana di valutazione e come una licenza a pagamento la rimuove.