FAQ di NextPDF

In sintesi

Questa pagina risponde alle domande che si presentano per prime quando si valuta NextPDF o si avvia un nuovo progetto. Ogni risposta è breve e rimanda alla pagina che la tratta per esteso. NextPDF è un motore PHP 8.4 che genera e ispeziona documenti in formato Portable Document Format (PDF) 2.0, il formato di file definito da ISO 32000-2.

Se si è alle primissime armi, leggere prima Iniziare, poi tornare qui per i dettagli.

Per iniziare

Quale edizione mi serve: Core, Pro o Enterprise?

Iniziare con Core. Il core open source (nextpdf/core) genera output PDF, rende l’HTML supportato in PDF e ispeziona i PDF sotto la licenza Apache-2.0 e senza alcun costo. Core produce già firme CMS SignedData per i livelli baseline PDF Advanced Electronic Signatures (PAdES) B-B e B-T. Scegliere Pro quando occorrono la generazione avanzata e le operazioni sui documenti, l’output di fattura elettronica (Factur-X / ZUGFeRD) o i workflow di firma avanzati come la firma remota, cloud-KMS e sequenziale. Scegliere Enterprise quando occorrono i workflow di authoring per l’archiviazione PDF/A, i livelli a lungo termine PAdES (B-LT / B-LTA) con un Document Security Store e i timestamp di documento, la firma supportata da hardware tramite un hardware security module (HSM) o le firme elettroniche qualificate. Pro ed Enterprise sono le due edizioni con licenza di NextPDF Premium, la linea a pagamento; si veda Scegliere il proprio percorso.

È davvero Apache-2.0?

Sì, per il core. nextpdf/core dichiara "license": "Apache-2.0" e distribuisce il testo completo della Apache License 2.0 nel proprio file LICENSE. È possibile usare, modificare, ridistribuire e commercializzare il core, fatti salvi i requisiti di attribuzione e NOTICE (Apache-2.0 §4). NextPDF Pro e NextPDF Enterprise sono edizioni commerciali proprietarie e non sono coperte da quella licenza. Il nome e il logo NextPDF sono marchi, distinti dalla licenza del codice. Si veda Licenze del prodotto.

Qual è la versione minima di PHP?

PHP 8.4. Il vincolo del pacchetto è >=8.4 <9.0, perciò Composer rifiuta di installare su PHP 8.3 o precedenti, o su PHP 9. NextPDF è pensato per un unico runtime moderno e ne usa direttamente le funzionalità di linguaggio. Si veda Installare NextPDF.

Serve un binario esterno o un browser headless?

No, non per il motore core. Il motore nativo è implementato in PHP e nelle estensioni PHP standard, senza alcun binario PDF esterno e senza alcun browser headless obbligatorio: l’API fluente e la pipeline HTML integrata writeHtml() vengono eseguite in-process senza browser e senza chiamate di rete. Un binario Chrome o Chromium è facoltativo e serve soltanto per il renderer Artisan (writeHtmlChrome()), che si installa separatamente come nextpdf/artisan. Anche i bridge Cloudflare e Gotenberg sono facoltativi e chiamano un servizio esterno. Si veda Scegliere il proprio percorso.

Quali estensioni PHP richiede?

Il composer.json del core richiede le estensioni standard ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl ed ext-openssl, che sono estensioni PHP comunemente disponibili; assicurarsi che siano installate e abilitate nel proprio runtime. ext-curl abilita i round-trip di rete facoltativi — l’apposizione di timestamp RFC 3161 e il recupero di asset remoti — perciò la generazione nativa offline non la utilizza, ma Composer la elenca comunque come requisito vincolante. Le integrazioni verificano all’avvio quelle di cui hanno bisogno e si arrestano con un messaggio chiaro se ne manca qualcuna. L’elenco completo risiede nel composer.json del pacchetto; si veda Installare NextPDF.

Come genero il mio primo PDF?

Installare il core, quindi costruire un documento con l’API fluente:

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

Lo si percorre passo passo in Il tuo primo PDF.

Edizioni e licenze

Core ha limiti di funzionalità o una filigrana?

No. Core è il motore open source per il set di funzionalità di Core, senza filigrana e senza schermata di sollecito. Per il set di funzionalità di Core — generazione, ispezione, cifratura, primitive di output PDF/A e PDF/UA e firma B-B/B-T con chiave software (senza i workflow Premium di validazione a lungo termine e custodia delle chiavi) — Core è completo. La filigrana di valutazione si applica soltanto a una concessione di valutazione Premium, in cui si prova l’intero set di funzionalità Pro ed Enterprise dietro un marchio rimovibile; una licenza a pagamento lo rimuove senza alcuna modifica al codice dell’applicazione. Si veda Licenze e attivazione.

Servono modifiche al codice per passare a Pro o Enterprise?

Per lo più no. Quando si installa nextpdf/premium, le integrazioni di framework e il server lo rilevano automaticamente ed espongono le funzionalità aggiuntive. La maggior parte delle applicazioni mantiene gli stessi punti di integrazione di alto livello; alcuni workflow Premium possono richiedere configurazione o chiamate specifiche per funzionalità. Si attiva un envelope di licenza firmato una volta per deployment. Si veda Licenze e attivazione.

Posso usare il core in un prodotto commerciale closed source?

Sì. La Apache License 2.0 non ha alcuna restrizione non commerciale. È possibile usare il core in prodotti commerciali closed source, a pagamento o interni, a condizione di rispettare gli obblighi di attribuzione e NOTICE e di non trattare la licenza del codice come permesso di usare il brand NextPDF. Si vedano Licenze del prodotto e Uso del marchio e del brand.

Funzionalità

Può leggere e analizzare i PDF, o solo scriverli?

Entrambe le cose, con un’avvertenza. NextPDF scrive i PDF e li legge anche: il modulo Inspect legge un file esistente in un InspectResult strutturato con dati di complessità, font, immagini e rischio, ed è possibile unire e suddividere documenti esistenti. Inspect è contrassegnato come sperimentale, perciò la forma del suo risultato può cambiare tra versioni minor — usarlo per diagnostica e gating, non come un contratto a lunga durata. Si veda il modulo Inspect.

Produce testo selezionabile e ricercabile?

Sì. Sia l’API fluente sia la pipeline integrata writeHtml() emettono vero contenuto testuale, non immagini rasterizzate, perciò l’output è selezionabile e ricercabile. Anche writeHtmlChrome() del renderer Artisan mantiene il testo selezionabile. Si veda Il tuo primo PDF.

Come funziona il rendering di HTML e CSS?

Il motore core include una pipeline HTML in puro PHP. writeHtml() rende un frammento HTML con un sottoinsieme supportato di CSS direttamente nella pagina, senza browser e senza chiamate di rete. Quando un layout richiede la piena fedeltà del browser — come flexbox, grid o web font — installare il renderer Artisan e chiamare writeHtmlChrome(). Prima di fare affidamento su una proprietà, consultare la matrice di supporto CSS.

Come funzionano i font?

Gli alias dei font standard integrati come Helvetica funzionano senza alcuna configurazione per il semplice testo WinAnsi, perciò il primo documento non richiede file di font. I font standard latini integrati si addicono al testo WinAnsi di base; Symbol e ZapfDingbats usano le proprie codifiche; per rendere altri script si registra e si incorpora un font la cui mappa dei caratteri e il cui percorso di shaping supportino quello script. Si vedano la matrice di supporto dei font e il modulo Font.

Supporta PDF/A e l’accessibilità (PDF/UA)?

Sì, con un confine chiaro: il supporto a un profilo non è conformità. Il core distribuisce il discriminatore di conformità e le primitive di tagging — enableTaggedPdf() abilita l’output della struttura tagged-PDF usata per i workflow PDF/UA, ed enablePdfA() seleziona un profilo di output PDF/A in Core; le edizioni Premium aggiungono al di sopra workflow e strumentazione di authoring per l’archiviazione di livello più alto (validazione, policy e operazioni di produzione). NextPDF emette gli artefatti strutturali che un profilo richiede; un validatore indipendente come veraPDF decide se un determinato file sia effettivamente conforme. Si vedano Conformità e il modulo Accessibilità.

Come firmo un PDF?

Il core può produrre firme Cryptographic Message Syntax (CMS) SignedData e può applicare timestamp RFC 3161 (il livello B-T), usando algoritmi a chiave software supportati tramite il provider di firma configurato. Il proprio codice dipende dal contratto SignerInterface, perciò la stessa chiamata funziona tra le edizioni. I livelli a lungo termine PAdES B-LT e B-LTA, la custodia delle chiavi HSM e PKCS#11 e le firme qualificate sono funzionalità Enterprise; i workflow di firma supportata da cloud e KMS sono disponibili in Pro. Core produce le strutture baseline B-B e B-T. Si veda il modulo Firma.

Produzione

È sicuro per worker e thread-safe?

Un Document è monouso: una volta che ne è stato scritto uno, creare una nuova istanza per il documento successivo anziché riutilizzarlo. Questo lo rende naturalmente adatto al modello per richiesta, per job usato da PHP-FPM, dai worker di coda e dai framework — ogni unità di lavoro costruisce il proprio documento. Quando si analizza o si compone input non attendibile, eseguire quel lavoro in un worker vincolato e mantenere strette le protezioni delle risorse (maxFiles, maxTotalBytes, maxBytes). Si vedano il modulo Document e il modello di minaccia del motore.

L’output è deterministico?

È strutturalmente deterministico, ma non identico byte per byte per impostazione predefinita. Due esecuzioni dello stesso input producono PDF strutturalmente equivalenti, ma ciascuno porta un trailer e un /ID di documento nuovi, perciò i byte differiscono. La firma e i timestamp, per progettazione, aggiungono ulteriore variazione a ogni esecuzione. Pianificare i confronti attorno all’uguaglianza strutturale, oppure normalizzare i campi volatili, anziché aspettarsi byte identici tra le esecuzioni.

Come lo distribuisco?

Committare composer.lock in modo che ogni worker distribuito risolva la stessa versione del motore, quindi distribuirlo come si farebbe con qualsiasi libreria PHP — la generazione nativa non richiede daemon, browser né rete; l’apposizione di timestamp (B-T), gli asset remoti o il bridge browser facoltativo richiedono un accesso di rete configurato. Se servizi non-PHP devono usare il motore, eseguire NextPDF Server, che lo espone tramite Model Context Protocol (MCP), REST e gRPC. Per Premium, collocare l’envelope di licenza firmato dove il deployment lo carica ed eseguire il passaggio di attivazione una tantum; lo stato della licenza memorizzato in cache fa sì che l’elaborazione normale non richieda un servizio di licenza, perciò i deployment air-gapped sono supportati. Si vedano Installare NextPDF e Licenze e attivazione.

Dove mi rivolgo quando qualcosa va storto?

NextPDF segnala gli errori tramite classe di eccezione PHP, non tramite un codice di errore di tipo stringa, e le eccezioni consapevoli del contesto portano campi diagnostici strutturati. La knowledge base di risoluzione dei problemi mappa i guasti comuni di firma, PDF/A, PDF/UA, font, tagging e cifratura alla loro causa e risoluzione.