Da HTML a PDF, la via semplice

Finora, in questo percorso, le pagine sono state costruite una chiamata alla volta. Molti documenti sono più rapidi da descrivere come markup, il formato di testo basato su tag usato per le pagine web. In questo tutorial si fornisce a NextPDF del codice Hypertext Markup Language (HTML) e il motore disegna la pagina.

Cosa si costruisce

Un report di una sola pagina generato da un’unica stringa HTML. Presenta un titolo colorato, un breve paragrafo e una tabella con una riga dei totali. Lo stile si definisce con i Cascading Style Sheets (CSS), il linguaggio di regole che controlla l’aspetto del markup. Nei tutorial precedenti si è usata l’interfaccia di programmazione delle applicazioni (API) fluente, ossia le chiamate di metodo concatenate. Qui, invece, si descrive il layout in markup ed è lo stesso motore a disegnarlo.

Passaggio 1: generare un report con stile da HTML

Creare un file denominato 01-html.php nella cartella del progetto, accanto a vendor. Incollarvi questo script completo:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

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

echo "Wrote out/reading-report.pdf\n";

Eseguire lo script dalla cartella del progetto:

php 01-html.php

Dovrebbe comparire una sola riga di output:

Wrote out/reading-report.pdf

Aprire out/reading-report.pdf in un qualsiasi visualizzatore Portable Document Format (PDF). Il titolo è blu scuro e la riga di intestazione della tabella ha lo stesso colore di sfondo.

Cosa è appena successo

@mkdir(__DIR__ . '/out'); crea la cartella di output. Il segno @ sopprime l’avviso quando la cartella esiste già, così le esecuzioni ripetute restano silenziose.
Document::createStandalone(), setTitle() e addPage() funzionano esattamente come nei tutorial precedenti. Il passaggio al markup non cambia nulla nella configurazione del documento.
writeHtml() legge la stringa una sola volta, dall’alto verso il basso, e disegna ogni elemento nella posizione corrente. Titoli e paragrafi diventano testo con stile. La tabella diventa una serie di righe dimensionate, con celle bordate.
Gli attributi style inline veicolano il CSS. Il motore comprende le proprietà più comuni come color, background-color, text-align e width.
Non è coinvolto alcun browser né software aggiuntivo. La pipeline è PHP puro all’interno del motore, quindi lo script viene eseguito ovunque funzioni l’installazione di Composer.

Il motore supporta un sottoinsieme pratico di HTML e CSS, non tutto ciò che un browser accetta. Tutto ciò che esula da quel sottoinsieme viene ignorato silenziosamente anziché generare un errore. La matrice di supporto CSS documenta esattamente ciò che è coperto. Per un approfondimento su questa pipeline, vedere Rendering di HTML in una pagina PDF.

Quando usare HTML e quando l’API fluente

Entrambi gli approcci si basano sullo stesso motore, quindi conviene scegliere quello più adatto al documento.

Scegliere writeHtml() quando il documento si legge come una pagina web: titoli, paragrafi, elenchi e tabelle. Il markup è più rapido da scrivere e più facile da modificare per i colleghi.
Scegliere l’API fluente quando serve un posizionamento esatto, come posizioni fisse o celle dimensionate con precisione. Il markup offre il flusso; le chiamate fluenti offrono il controllo.
Consultare la matrice di supporto CSS prima di affidarsi a una proprietà. Quando uno stile non è coperto, conviene costruire quella parte con le chiamate fluenti.

Il confine di sicurezza

Nella realtà, l’HTML proviene spesso dall’esterno del codice, per esempio da un modulo o da un database. Va trattato come input non attendibile e va validato o ripulito prima del rendering. Per impostazione predefinita, la pipeline integrata non esegue script e non recupera risorse remote. Questo comportamento predefinito mantiene il renderer prudente anche quando il markup non lo è. Se servono opzioni di rendering di livello browser, vedere Scegliere il percorso.

Se qualcosa è andato storto

Failed to open stream: No such file or directory di solito significa che lo script non trova vendor/autoload.php. Eseguirlo dalla cartella in cui è stato lanciato Composer.
Uno stile mancante è di solito una proprietà che non rientra nel sottoinsieme supportato. Il motore ignora ciò che non supporta anziché fallire. Confrontare il proprio markup con la matrice di supporto CSS.
Un’eccezione durante il rendering indica il problema esatto. Cercarla nel riferimento errori di rendering e input/output.

Per tutto il resto, iniziare dalla guida alla risoluzione dei problemi.

Passo successivo

Ora si sa costruire documenti sia una chiamata alla volta sia a partire dal markup. Completare il percorso con Dove andare ora. Mappa il cookbook, il riferimento e le guide da usare dopo questo percorso.