Configurare il Loader ionCube per le edizioni premium di NextPDF

In breve

Alcune distribuzioni premium di NextPDF vengono fornite come PHP codificato con ionCube, quindi il corrispondente Loader ionCube deve essere installato nel runtime PHP prima che il codice possa essere eseguito. Questo vale per:

• Le build di valutazione di NextPDF Pro ed Enterprise, e
• La build ufficiale (a pagamento) di NextPDF Pro.

Per il recapito ufficiale di NextPDF Enterprise, il meccanismo di pacchettizzazione dipende dal proprio contratto. Seguire le istruzioni di recapito indicate nei termini di licenza anziché presumere un runtime specifico; vedere Licenze e attivazione.

Questa pagina è una guida pratica alla configurazione: che cos’è ionCube, come installare e verificare il Loader, dove va collocato il file di licenza per la build a pagamento di Pro codificata con ionCube, come eseguirlo nei container e come risolvere i problemi più comuni. La versione di PHP supportata è la 8.4, e il Loader installato deve corrispondere esattamente a quel runtime.

Che cos’è ionCube e perché NextPDF lo utilizza

ionCube è un encoder PHP commerciale abbinato a un componente di runtime gratuito chiamato Loader ionCube. Il Loader è un’estensione PHP (Zend). All’avvio di PHP, il Loader consente di decodificare ed eseguire i file codificati; senza di esso, un file codificato non può essere eseguito e PHP segnala invece un errore del loader.

NextPDF utilizza la codifica ionCube per proteggere il codice sorgente premium proprietario continuando comunque a fornire PHP installabile, che si distribuisce ed esegue come qualsiasi altro pacchetto Composer. La codifica non modifica il modo in cui si richiama la libreria — l’applicazione fa riferimento agli stessi contratti pubblici — aggiunge soltanto il requisito che il Loader sia presente nel runtime.

Per i download del Loader e per le istruzioni autorevoli e specifiche per versione, utilizzare la documentazione del fornitore su ioncube.com (la documentazione e la guida all’installazione del Loader ionCube). Questa pagina tratta la configurazione specifica di NextPDF; il fornitore è la fonte attendibile per il Loader stesso.

Requisiti

Installare il Loader ionCube che corrisponde al proprio runtime PHP su ogni asse. Una mancata corrispondenza anche su uno solo di questi è la causa di errore più comune:

Asse	Deve corrispondere a
Versione di PHP	8.4 (il premium di NextPDF richiede >=8.4 <9.0).
Sistema operativo	Il sistema operativo a cui è destinato il bundle del Loader (Linux, Windows, macOS).
Architettura	L’architettura della CPU dell’host, in genere a 64 bit (x86-64 o aarch64).
Thread safety	Non-thread-safe (NTS) o thread-safe (ZTS), in base alla propria build di PHP.

Oltre al Loader, occorre anche:

• Il pacchetto premium di NextPDF installato tramite Composer — nextpdf/pro, nextpdf/enterprise o il metapacchetto nextpdf/premium.
• Per le build a pagamento, il proprio file di licenza. Per la build a pagamento di Pro codificata con ionCube, vedere Collocazione della licenza più avanti.

Per leggere i valori della propria build attuale, eseguire php -i (o richiamare phpinfo()) e controllare le righe PHP Version, Architecture e Thread Safety. Sulla maggior parte dei deployment CLI e PHP-FPM la thread safety è disabilitata (NTS); il classico mod_php di Apache su alcune piattaforme è ZTS. Scaricare il bundle del Loader per quei valori esatti.

Installare il Loader

I passaggi seguenti descrivono il flusso generale. Fare riferimento alla documentazione del Loader ionCube su ioncube.com per i nomi esatti dei file e l’organizzazione delle directory del bundle attuale.

1. Scaricare il bundle del Loader corrispondente al proprio ambiente (PHP 8.4, il proprio sistema operativo, l’architettura e NTS/ZTS). Il bundle contiene un file loader per ogni versione di PHP e variante di thread safety.

2. Collocare il file loader nella directory delle estensioni PHP. Utilizzare la extension_dir riportata da php -i. Su Linux/macOS il file è ioncube_loader_<os>_8.4.so (usare ..._8.4_ts.so per una build ZTS); su Windows è ioncube_loader_win_8.4.dll (oppure la variante ZTS ..._ts.dll).

3. Registrarlo in php.ini come zend_extension. Il Loader ionCube deve essere caricato come zend_extension, non come semplice extension, e deve essere caricato prima delle altre estensioni. Aggiungere una singola riga, usando un percorso assoluto al file loader:

   zend_extension=/full/path/to/ioncube_loader_lin_8.4.so

   Su Windows, usare il percorso completo al file .dll:

   zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"

   Se la propria piattaforma utilizza directory di inclusione in stile conf.d, collocare questa riga in un file letto per primo (per esempio un 00-ioncube.ini) in modo che il Loader si inizializzi prima delle altre estensioni.

4. Riavviare il runtime PHP. Riavviare PHP-FPM, il proprio server web (Apache/Nginx) oppure rieseguire semplicemente la CLI — a seconda di ciò che esegue l’applicazione. Un processo a lunga esecuzione mantiene la vecchia configurazione finché non viene riavviato.

Verificare

Confermare che il Loader sia attivo prima di provare a caricare NextPDF.

Per prima cosa, controllare il banner della versione di PHP. Quando il Loader è installato, php -v aggiunge una riga che lo nomina:

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

La frase “with the ionCube PHP Loader” è il segnale che il Loader è attivo per quel runtime. Per un deployment web (FPM / mod_php), il banner della CLI non è sufficiente — quel runtime può usare un php.ini diverso. Confermare il runtime web con un piccolo script servito dal server web:

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

Infine, confermare che una classe premium di NextPDF venga effettivamente caricata attraverso l’autoloader di Composer. Questo dimostra che il codice codificato viene eseguito end-to-end:

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

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

Se php -v nomina il Loader, il phpinfo() web mostra la sezione ionCube e la classe premium si risolve, allora il Loader è configurato correttamente.

Collocazione della licenza (la build a pagamento di Pro codificata con ionCube)

ionCube utilizza un modello di licenza semplice: il codice codificato verifica la presenza di un file di licenza in fase di esecuzione e rifiuta di essere eseguito quando il file è mancante, illeggibile o scaduto. Questo vale per la build a pagamento di Pro codificata con ionCube — per essa, si colloca il file di licenza fornito con l’acquisto in un punto in cui il runtime possa trovarlo.

Questo meccanismo del file di licenza di ionCube è specifico della build codificata con ionCube. Il recapito ufficiale di NextPDF Enterprise non viene qui presunto come codificato con ionCube; la sua pacchettizzazione e la gestione della licenza sono regolate dai propri termini di licenza — vedere Licenze e attivazione.

I percorsi esatti dipendono dall’ambiente, quindi conviene mantenere l’indicazione generale:

• Collocare il file di licenza nella posizione specificata dalle istruzioni di recapito di NextPDF — di solito accanto al pacchetto codificato o in una directory che l’applicazione può leggere. Assicurarsi che l’utente del processo PHP disponga del permesso di lettura.
• Non rinominare il file a meno che le istruzioni non lo richiedano; il loader cerca un nome specifico.
• Nei container e nei deployment in sola lettura, montare o copiare il file di licenza nell’immagine o in un percorso scrivibile e leggibile visibile al runtime (vedere Docker e container).

Il file di licenza regola l’attivazione a livello di runtime; è distinto dalla licenza a livello di applicazione che seleziona l’edizione e le funzionalità. Per i termini, le durate e ciò a cui dà diritto il proprio abbonamento, vedere Licenze e attivazione e il proprio contratto di licenza — questa pagina non definisce i termini di licenza.

Risoluzione dei problemi

”Loader not installed” / “Failed loading … ioncube_loader”

Il Loader non è attivo nel runtime che ha eseguito il codice, oppure il percorso è errato. Ricontrollare che la riga zend_extension punti a un file esistente con un percorso assoluto, che si sia riavviato il runtime e che si sia verificato lo stesso runtime (CLI vs FPM) con php -v / phpinfo(). Un messaggio Failed loading di solito significa che il file esiste ma non corrisponde alla build di PHP (vedere il punto successivo).

Mancata corrispondenza di versione di PHP, NTS/ZTS o architettura

Un Loader compilato per una versione di PHP, una modalità di thread safety o un’architettura diversa non verrà caricato. Confermare PHP Version, Thread Safety e Architecture da php -i, quindi installare il file del Loader per PHP 8.4 con il corrispondente NTS/ZTS e la corretta architettura a bit. Il suffisso 8.4 rispetto a 8.4_ts (o _ts.dll) è il selettore della thread safety — usare quello sbagliato è un errore frequente.

Ordine di caricamento del Loader

Il Loader ionCube deve essere un zend_extension e deve inizializzarsi prima delle altre estensioni. Se si vedono avvisi sul caricamento del Loader dopo le altre estensioni, spostare la sua riga zend_extension più in alto — oppure, con un’organizzazione conf.d, assegnare al suo file di inclusione un nome che venga ordinato per primo (per esempio 00-ioncube.ini).

CLI, FPM e il server web utilizzano file php.ini differenti

PHP carica comunemente un php.ini diverso per la CLI rispetto a PHP-FPM o mod_php. Configurare solo la CLI lascia il runtime web privo del Loader (o viceversa). Eseguire php --ini per vedere quale file utilizza la CLI, e controllare la riga Loaded Configuration File nell’output di phpinfo() del web. Aggiungere la riga zend_extension a ogni php.ini che esegue NextPDF, e riavviare ciascun runtime.

File di licenza non trovato o scaduto

Per la build a pagamento di Pro codificata con ionCube, un file di licenza mancante, illeggibile o scaduto impedisce l’esecuzione del codice codificato. Verificare che il file si trovi nella posizione prevista, che l’utente del processo PHP possa leggerlo e che non sia scaduto. Per le domande su rinnovo e durate, vedere Licenze e attivazione e il proprio contratto di licenza.

Interazioni con OPcache

OPcache memorizza nella cache gli script compilati, ma i file codificati con ionCube vengono decodificati dal Loader in fase di esecuzione. Se si è modificato il Loader o la sua configurazione e il runtime continua a comportarsi come se fosse assente, riavviare il runtime PHP (operazione che svuota OPcache) anziché affidarsi a un hot reload. Mantenere il zend_extension di ionCube registrato in modo che si carichi prima di OPcache; i due coesistono, e php -v dovrebbe elencarli entrambi.

Docker e container

In un deployment containerizzato, installare il Loader nell’immagine e assicurarsi che corrisponda alla build di PHP del container — non a quella del proprio host. L’immagine di base fissa la versione di PHP, il sistema operativo, l’architettura e la modalità di thread safety, quindi scaricare il bundle del Loader per quei valori.

Una tipica build dell’immagine:

1. Partire da un’immagine di base PHP 8.4 (notare se è NTS o ZTS — i tag ufficiali php:8.4-cli / 8.4-fpm / 8.4-apache sono NTS, mentre i tag che contengono zts sono thread-safe; scegliere il Loader corrispondente).
2. Aggiungere il file del Loader ionCube corrispondente alla extension_dir dell’immagine.
3. Scrivere la riga zend_extension=... nel php.ini dell’immagine (o in un’inclusione conf.d).
4. Per la build a pagamento di Pro codificata con ionCube, fornire il file di licenza copiandolo nell’immagine o montandolo in fase di esecuzione in un percorso che il container possa leggere.

Poiché il Loader è incorporato nell’immagine, lo stesso container viene eseguito in modo identico ovunque. Se in seguito si aggiorna la versione di PHP dell’immagine di base, sostituire il file del Loader con la build che corrisponde al nuovo runtime.

Vedere anche

• Licenze e attivazione
• NextPDF Premium
• Scegliere il percorso