Configurare NextPDF ed eseguire il rendering del primo PDF

NextPDF è una libreria PHP che crea file PDF (Portable Document Format). In questo tutorial viene installata in una cartella vuota per eseguire il rendering del primo documento di una pagina. Servono un terminale e circa dieci minuti.

Che cosa si costruisce

Si costruisce un piccolo progetto che contiene un solo script, 01-hello.php. Lo script esegue il rendering di una singola pagina con una riga di titolo in grassetto e un paragrafo. Salva il risultato come out/hello.pdf. Lungo il percorso si imparano due comandi che confermano la corretta installazione.

Questa pagina illustra un solo percorso di installazione: una cartella vuota più il pacchetto del motore. Esistono altri percorsi, come gli adattatori per framework, i renderer basati su browser e il client Python. Questi sono trattati in Installazione e Scegliere il proprio percorso. Oggi non servono.

Passo 1: creare un progetto e installare NextPDF

Composer è il gestore di pacchetti per PHP. Scarica le librerie nel progetto e genera un autoloader. Un autoloader è un piccolo file PHP che individua le classi delle librerie, così non è mai necessario scrivere lunghi elenchi di include.

Aprire un terminale ed eseguire questi tre comandi:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer stampa l’avanzamento mentre risolve e scarica i pacchetti. Le righe esatte variano in base alla versione di Composer e alla cache locale. Un’installazione riuscita termina senza testo di errore e si presenta all’incirca così:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Che cosa è appena successo

Composer ha creato tre elementi nella cartella. composer.json registra che il progetto dipende dal motore. composer.lock fissa la versione esatta installata, così un’installazione successiva risolve lo stesso codice. La cartella vendor/ contiene i pacchetti scaricati, incluso vendor/autoload.php. Lo script carica quell’unico file e ogni classe del motore diventa disponibile.

Durante l’installazione Composer ha anche verificato la configurazione di PHP. Il motore dichiara le estensioni PHP di cui ha bisogno. Le estensioni sono moduli opzionali integrati in PHP. Se ne manca una, Composer si arresta e la indica, anziché lasciare un’installazione non funzionante.

Passo 2: eseguire il rendering del primo PDF

Creare un file di nome 01-hello.php accanto a composer.json. Incollarvi questo programma completo:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Eseguirlo:

php 01-hello.php

Dovrebbe comparire esattamente una riga:

Wrote out/hello.pdf

Aprire out/hello.pdf in un qualsiasi visualizzatore PDF. Compare la riga di titolo in grassetto con il paragrafo sottostante e, nella maggior parte dei visualizzatori, «Hello from NextPDF» appare nella barra del titolo della finestra.

Che cosa è appena successo

Analizzare lo script dall’alto verso il basso:

require carica l’autoloader di Composer, così la classe Document viene risolta.
@mkdir crea la cartella out/. La @ iniziale mantiene silenzioso lo script quando la cartella esiste già, così è possibile eseguirlo di nuovo.
Document::createStandalone() restituisce un documento nuovo. È pensato per brevi script da riga di comando esattamente come questo.
setTitle() imposta il titolo del documento, che i visualizzatori mostrano nella barra del titolo della finestra.
addPage() aggiunge una pagina vuota e posiziona il cursore in alto a sinistra.
setFont() sceglie una famiglia di caratteri, uno stile e una dimensione in punti. I punti sono l’unità standard per le dimensioni dei caratteri nella stampa. 'B' indica il grassetto e '' indica il carattere normale. La famiglia denominata helvetica è integrata, quindi non serve alcun file di carattere.
cell() scrive una riga di testo alla posizione del cursore. Una larghezza di 0 significa «estendere fino al margine destro». newLine: true sposta poi il cursore verso il basso, come premere Invio.
save() genera il PDF finito e lo scrive su disco.

Un documento produce un file. Quando serve un secondo PDF, creare un nuovo documento anziché riutilizzare quello precedente.

Passo 3: verificare la configurazione

Due rapidi controlli confermano che questa installazione continuerà a funzionare oltre un singolo script.

Per prima cosa, elencare le estensioni presenti in PHP:

php -m

Cercare nell’elenco curl, gd, intl, mbstring, openssl e zlib. Il motore si basa su queste sei. Composer le ha già verificate nel Passo 1, quindi dovrebbero comparire tutte.

Poi, eseguire il controllo di integrità del motore:

vendor/bin/nextpdf doctor

Su Windows, richiamare invece vendor\bin\nextpdf doctor. Il comando esamina la versione di PHP, le estensioni, la cartella temporanea e la configurazione. Ogni controllo stampa [OK], [WARN] o [FAIL], seguito da un verdetto complessivo.

Che cosa è appena successo

Leggere prima il blocco Extensions. Sei righe [OK] con i nomi curl, gd, intl, mbstring, openssl e zlib indicano che l’installazione è pronta per ogni tutorial successivo.

Il report elenca anche le funzionalità del motore. Nell’installazione gratuita Core, le funzionalità che appartengono ai pacchetti commerciali stampano [FAIL] con un messaggio che indica il pacchetto che le fornisce. Qui è previsto e può portare il verdetto complessivo a UNHEALTHY anche se la configurazione Core è corretta. Per questi tutorial, il blocco Extensions è il segnale che conta.

Se qualcosa non ha funzionato

Confrontare prima il sintomo con questi casi comuni:

composer: command not found significa che Composer manca o non è nel PATH. Installarlo da getcomposer.org, quindi ripetere il Passo 1.
Failed opening required '.../vendor/autoload.php' significa che lo script è stato eseguito fuori dalla cartella del progetto o che l’installazione non è terminata. Spostarsi nella cartella del Passo 1 ed eseguire composer install.
Se Composer si arresta durante il Passo 1 e indica un’estensione PHP mancante, abilitare quell’estensione nel file php.ini. Confermarla con php -m, quindi ripetere l’installazione.
Una riga [FAIL] nel blocco Extensions del doctor indica un’estensione PHP mancante. Abilitarla in php.ini, confermare con php -m ed eseguire di nuovo il doctor. Le righe [FAIL] di funzionalità che indicano un pacchetto commerciale sono previste nell’installazione Core e qui non richiedono alcuna azione.

Per qualsiasi altro caso, partire dalla knowledge base di risoluzione dei problemi. Se uno script solleva un’eccezione, cercarne la classe nel riferimento degli errori; la maggior parte degli errori dei principianti compare in errori generali.

Passi successivi

L’installazione funziona e il primo file è stato generato. Proseguire con Testo, caratteri e nozioni di base sulle pagine per controllare le dimensioni delle pagine, i caratteri integrati, i colori e l’allineamento.