Premium edizione

Installare e autenticare il pacchetto premium privato di NextPDF con Composer

In sintesi

I pacchetti premium di NextPDF — nextpdf/pro, nextpdf/enterprise e il metapacchetto nextpdf/premium — non sono pubblicati sull’indice pubblico Packagist. Risiedono in un repository Composer privato legato al proprio account, perciò un semplice composer require nextpdf/premium non riesce a trovarli finché non si comunicano a Composer due cose: dove si trova il repository e come autenticarsi presso di esso.

Questa pagina riprende dal punto in cui si ferma Licenze e attivazione. Una volta ottenute le credenziali, si configura Composer una volta sola, si installa il pacchetto e lo si verifica. Tutto ciò che è descritto qui è comportamento standard di Composer; nulla di tutto questo è strumentazione specifica di NextPDF. Trattare il token del repository come una chiave API, esattamente come la pagina sulle licenze tratta l’envelope di licenza firmato: tenerlo fuori dal controllo di versione pubblico.

Da dove provengono le credenziali

L’URL del repository privato, il nome utente e il token vengono emessi dopo aver ottenuto una licenza — acquistando tramite il nostro Merchant of Record oppure avviando una valutazione — dal portale delle licenze. Per il percorso d’acquisto, il modello a due contratti (acquisto rispetto a licenza) e a chi rivolgersi per la fatturazione rispetto all’assistenza sul prodotto, vedere Acquisto e licenze.

1. Dove risiedono i pacchetti premium

Il portale delle licenze emette due elementi per l’installazione:

Un URL del repository Composer privato — l’endpoint autenticato che serve i pacchetti premium.
Un nome utente e un token (una coppia di credenziali HTTP Basic) per quell’endpoint.

Ovunque questa pagina mostri un host del repository, sostituirlo con l’URL del repository ottenuto dal proprio portale delle licenze. Ovunque mostri un nome utente o un token, sostituirli con le credenziali emesse per il proprio account. NextPDF non pubblica un unico URL condiviso; l’endpoint e le credenziali sono specifici del proprio abbonamento.

2. Aggiungere il repository privato a composer.json

Comunicare a Composer il repository con un solo comando, eseguito nella radice del proprio progetto:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf

Sostituire https://repo.example.com/nextpdf con l’URL ottenuto dal proprio portale. Il tipo di repository composer indirizza Composer verso un indice in formato Composer (un packages.json), che è ciò che serve un endpoint di pacchetti privati.

Quel comando scrive un blocco repositories in composer.json. È possibile aggiungerlo anche a mano:

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://repo.example.com/nextpdf"
        }
    }
}

La definizione del repository non è un segreto — indica soltanto una posizione, perciò è sicuro committarla. Sono le credenziali del passaggio successivo ciò che occorre proteggere.

3. Autenticarsi con uno dei tre metodi standard

Composer legge le credenziali HTTP Basic per un host da diverse posizioni. Scegliere il metodo corrispondente al luogo in cui si effettua l’installazione.

Metodo A — auth.json (sviluppo locale)

Su una macchina di sviluppo, memorizzare la credenziale in un file auth.json accanto a composer.json. Usare l’host dell’URL del repository come chiave:

composer config --auth http-basic.repo.example.com your-username your-token

Questo crea (o aggiorna) un auth.json locale al progetto:

{
    "http-basic": {
        "repo.example.com": {
            "username": "your-username",
            "password": "your-token"
        }
    }
}

La chiave host (repo.example.com) deve corrispondere esattamente all’host nell’URL del repository — Composer abbina le credenziali alle richieste in base all’host.

Metodo B — variabile d’ambiente COMPOSER_AUTH (CI/CD)

Nell’integrazione continua di solito non si desidera avere un file su disco. Composer legge le stesse credenziali dalla variabile d’ambiente COMPOSER_AUTH, il cui valore è una stringa JSON con la stessa forma di auth.json:

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"your-username","password":"your-token"}}}'
composer install

Iniettare COMPOSER_AUTH dal magazzino dei segreti del proprio provider CI (variabile mascherata, segreto o binding di vault) in modo che il token non compaia mai nella definizione della pipeline o nel log di build.

Metodo C — autenticazione globale per utente (workstation condivisa)

Per autenticare ogni progetto dell’utente corrente senza un file per progetto, scrivere la credenziale nell’auth.json globale di Composer:

composer config --global --auth http-basic.repo.example.com your-username your-token

Questo memorizza la credenziale nella directory home di Composer (COMPOSER_HOME, ad esempio ~/.composer/auth.json o ~/.config/composer/auth.json). Si applica a tutti i progetti che si compilano come quell’utente, perciò è preferibile il Metodo A o B quando una credenziale deve essere circoscritta a un singolo progetto o a una singola pipeline.

4. Tenere le credenziali fuori dal controllo di versione

L’URL del repository è sicuro da committare; il token no. Due regole tengono i segreti fuori dalla cronologia:

Ignorare il file auth locale. Aggiungere auth.json a .gitignore in modo che una credenziale locale al progetto non venga mai committata:
```
/auth.json
```
Iniettare il token in CI/CD. Fornire COMPOSER_AUTH (Metodo B) dal magazzino dei segreti della propria pipeline anziché committare un auth.json nel repository o incorporarlo in un layer di immagine di un container.

Se un token viene mai committato o stampato, ruotarlo tramite il proprio portale delle licenze — trattarlo come compromesso, esattamente come si farebbe con una chiave API trapelata.

5. Installare e verificare

Con il repository e le credenziali a posto, richiedere l’edizione a cui dà diritto la propria licenza:

# Pick the package for your entitlement:
composer require nextpdf/pro
# or
composer require nextpdf/enterprise
# or the metapackage, which the licensing page uses:
composer require nextpdf/premium

Fissare una versione major se il proprio progetto preferisce vincoli espliciti — ad esempio composer require nextpdf/pro:^3, in linea con il vincolo usato dalle pagine del modulo Pro.

Verificare che Composer abbia risolto il pacchetto privato e che il suo autoloader funzioni. Confermare prima che il pacchetto sia installato eseguendo composer show <installed-package> per l’edizione richiesta — ad esempio composer show nextpdf/pro, composer show nextpdf/enterprise o composer show nextpdf/premium:

# Use the package name you actually required:
composer show nextpdf/pro
# or
composer show nextpdf/enterprise
# or
composer show nextpdf/premium

Se composer show riporta il pacchetto e la sua versione, il pacchetto privato è stato risolto. Rieseguire composer dump-autoload rigenera quindi l’autoloader in modo pulito, così che le classi del pacchetto siano individuabili:

composer dump-autoload

Come verifica facoltativa a livello di codice, è possibile confermare che una classe della propria edizione installata venga caricata tramite autoload. Non indovinare un nome di classe: aprire l’API reference per l’edizione installata e scegliere una qualsiasi classe pubblica documentata, quindi verificare che si risolva. La classe da cercare dipende dalla propria edizione — una classe presente in un’edizione può non esserlo in un’altra, e il caricamento di una singola classe dimostra soltanto che quella edizione è presente, non che ogni edizione sia installata.

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

// Replace the placeholder with a documented public class from YOUR edition's
// API reference. Do not hardcode a class from a different edition.
$class = 'Your\\Installed\\Edition\\DocumentedClass';
var_dump(class_exists($class));

Installare il pacchetto non equivale ad attivarlo. Il pacchetto da solo non concede le funzionalità Pro o Enterprise — la licenza firmata che si attiva seleziona l’edizione attiva. Dopo un’installazione riuscita, seguire Licenze e attivazione per collocare e attivare l’envelope di licenza e, per le build codificate con ionCube, configurare il ionCube Loader.

Risoluzione dei problemi

401 Unauthorized o 403 Forbidden

Composer ha raggiunto il repository ma le credenziali sono state rifiutate o risultano insufficienti. Confermare che la chiave host in auth.json / COMPOSER_AUTH corrisponda esattamente all’host del repository (senza schema, senza percorso, senza barra finale), che il nome utente e il token siano attuali e che il token non sia scaduto né sia stato ruotato nel proprio portale. Un 401 indica una credenziale errata o mancante; un 403 indica una credenziale valida il cui ambito non include il pacchetto o l’edizione richiesta — verificare che il proprio abbonamento dia diritto al nome del pacchetto che si sta richiedendo.

Pacchetto non trovato / “could not find a matching version”

Di solito ciò significa che Composer non ha usato o non ha raggiunto l’indice privato (perciò ha cercato soltanto sul Packagist pubblico), oppure ha raggiunto l’indice ma non ha trovato alcun pacchetto o alcuna versione installabile che corrisponda. Confermare che il blocco repositories.nextpdf esista nel composer.json di questo progetto, con "type": "composer" e l’URL corretto, e che si stia richiedendo il nome esatto del pacchetto (nextpdf/pro, nextpdf/enterprise o nextpdf/premium). Eseguire composer config repositories per stampare ciò che Composer vede. Un errore di battitura nell’URL o un blocco di repository mancante è una causa comune, ma verificare anche che il proprio vincolo di versione corrisponda a una versione pubblicata, che il requisito di piattaforma PHP del progetto (e minimum-stability) consenta il pacchetto e che l’ambito del proprio token copra effettivamente il pacchetto che si sta richiedendo.

Il token funziona in locale ma fallisce in CI

Il file auth.json locale non è presente sul runner. Impostare COMPOSER_AUTH dal magazzino dei segreti della propria CI (Metodo B) anziché affidarsi a un file, e assicurarsi che la variabile sia esportata prima dell’esecuzione di composer install. Nelle build containerizzate, passare il segreto in fase di build senza persisterlo in un layer dell’immagine.

Chiave host errata

Le credenziali vengono abbinate in base all’host. Se l’URL del repository è https://repo.example.com/nextpdf, la chiave deve essere repo.example.com — non l’URL completo e non un sottopercorso. Una chiave non corrispondente fa sì che Composer invii la richiesta senza autenticazione, il che si manifesta come un 401.