Come Smettere di Lottare con la Generazione di PDF in Laravel

Generare documenti PDF sul web è sempre stato una bella sfida. Pensate a quante volte avete cercato di creare il layout perfetto per una fattura o un report, solo per scoprire che i caratteri si sono spostati, le tabelle si sono disallineate, o le immagini sono completamente scomparse. Di solito la scelta ricade su utility di sistema complesse come wkhtmltopdf, che richiedono configurazione del server, e servizi cloud a pagamento.

Se lavorate con lo stack Laravel, esiste una soluzione collaudata nel tempo — il pacchetto laravel-dompdf di Barry van den Heuvel. È un wrapper attorno alla libreria Dompdf che prende il vostro familiare template Blade e lo converte in un file PDF. Nessuna dipendenza server extra, solo PHP.

Cosa c'è sotto il cofano

Il progetto essenzialmente fa una cosa: connette la potenza di Laravel con il motore Dompdf. La caratteristica principale è che non dovete imparare una nuova sintassi per il layout dei documenti. Create una View normale, passate i dati e il pacchetto gestisce il rendering.

Interessante notare che il pacchetto supporta non solo Laravel standard ma anche Lumen. Questo è utile se state estraendo la generazione di documenti in un microservizio separato.

Come funziona in pratica

L'installazione è standard tramite Composer:

composer require barryvdh/laravel-dompdf

Dopo di che, avete accesso al facade Pdf. L'esempio più semplice per creare un file assomiglia a questo:

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

Il metodo loadView prende il vostro file Blade, passa le variabili e genera un oggetto che potete immediatamente inviare all'utente per il download o semplicemente visualizzare nel browser tramite stream().

Configurazione flessibile delle pagine

Spesso dovete cambiare l'orientamento della pagina o il formato della carta direttamente nel codice. Ad esempio, l'orientamento orizzontale funziona meglio per tabelle ampie:

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

A proposito, se dovete salvare il file su disco invece di servirlo all'utente, il metodo save() lo farà in un'unica azione.

Supporto PDF/3b e fatture elettroniche

Le versioni recenti (3.x) hanno aggiunto il supporto per lo standard PDF/3b. Questo è fondamentale per l'archiviazione a lungo termine dei documenti. Ma c'è un problema: questo standard richiede che tutti i caratteri siano incorporati nel file. L'Helvetica o il Times standard non funzioneranno — dovrete usare qualcosa come DejaVu Sans.

Per chi lavora sull'automazione contabile, il pacchetto ora supporta i formati Zugferd e Factur-X. Questo è quando un file XML con i dati della fattura viene incorporato direttamente nel PDF. Sembra qualcosa del genere:

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

Alcuni consigli sul layout

Dompdf non è un motore browser completo. Gestisce bene CSS 2.1 e alcune proprietà CSS 3, ma non cercate di usare Flexbox o Grid. Le buone vecchie tabelle e i float sono la vostra scommessa migliore.

Due cose che vi faranno risparmiare molto tempo:

1. Specificate sempre la codifica nel vostro template: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Senza questo, il cirillico diventerà punti interrogativi.
2. Per i salti pagina, usate la proprietà CSS page-break-after: always. Questo è il modo più affidabile per far iniziare la stampante un nuovo foglio dove vi serve.

Vale la pena usarlo

laravel-dompdf è un cavallo da lavoro. È perfetto per generare documenti da semplici a complessità media: fatture, report di servizio, estratti conto semplici.

Il vantaggio principale è la semplicità. Non dovete installare Node.js, Puppeteer, o configurare binari del server. Tutto funziona out of the box su hosting PHP standard.

Tuttavia, se dovete renderizzare grafici JavaScript complessi o il vostro layout è pesante con trucchi CSS moderni, Dompdf potrebbe avere difficoltà. In questi casi, è meglio guardare a strumenti basati su Chromium. Ma per il 90% dei task di un developer backend, questo pacchetto è più che sufficiente.

Il progetto è vivo e mantenuto attivamente (oltre 7.000 stelle su GitHub) ed è supportato da uno dei collaboratori più noti della community Laravel. Se non l'avete ancora provato — ora è il momento di segnarvelo.