Stop met worstelen met PDF-generatie in Laravel

Het genereren van PDF-documenten op het web is altijd een flinke uitdaging geweest. Denk aan hoe vaak je geprobeerd hebt om de perfecte factuur of het perfecte rapport op te maken, om erachter te komen dat lettertypen zijn verschoven, tabellen uit elkaar zijn geraakt, of afbeeldingen helemaal zijn verdwenen. Meestal komt de keuze neer op complexe systeemhulpmiddelen zoals wkhtmltopdf, die serverconfiguratie vereisen, en betaalde cloudservices.

Als je met de Laravel-stack werkt, is er een tijd-geprüefde oplossing — het laravel-dompdf-pakket van Barry van den Heuvel. Het is een wrapper rond de Dompdf-bibliotheek die je vertrouwde Blade-template neemt en omzet naar een PDF-bestand. Geen extra serverafhankelijkheden, gewoon PHP.

Wat zit er onder de motorkap

Het project doet in essentie één ding: het verbindt de kracht van Laravel met de Dompdf-engine. Het belangrijkste kenmerk is dat je geen nieuwe syntaxis hoeft te leren voor documentlay-out. Je maakt een gewone View, geeft er data aan door, en het pakket verzorgt het renderen.

Interessant is dat het pakket niet alleen standaard Laravel ondersteunt, maar ook Lumen. Dit is handig als je documentgeneratie uitbreekt naar een aparte microservice.

Hoe het in de praktijk werkt

Installatie is standaard via Composer:

composer require barryvdh/laravel-dompdf

Daarna krijg je toegang tot de Pdf facade. Het eenvoudigste voorbeeld van het maken van een bestand ziet er zo uit:

use Barryvdh\DomPDF\Facade\Pdf;

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

De loadView methode pakt je Blade-bestand, geeft variabelen eraan door, en genereert een object dat je direct naar de gebruiker kunt sturen voor download of gewoon in de browser kunt weergeven via stream().

Flexibele pagina-instellingen

Vaak moet je de pagina-orientatie of het papierformaat direct in de code aanpassen. Bijvoorbeeld, liggende orientatie werkt beter voor brede tabellen:

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

Trouwens, als je het bestand naar schijf moet opslaan in plaats van het aan de gebruiker te serveren, zal de save() methode dit in één actie doen.

PDF/A-3b-ondersteuning en elektronische facturen

Recente versies (3.x) voegden ondersteuning toe voor de PDF/A-3b-standaard. Dit is cruciaal voor langetermijn-documentarchivering. Maar er is een addertje onder het gras: deze standaard vereist dat alle lettertypen in het bestand worden ingebed. Standaard Helvetica of Times werken niet — je zult iets als DejaVu Sans moeten gebruiken.

Voor degenen die werken aan boekhoudautomatisering ondersteunt het pakket nu Zugferd- en Factur-X-formaten. Dit is wanneer een XML-bestand met factuurgegevens direct in de PDF wordt ingebed. Het ziet er ongeveer zo uit:

$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'
);

Enkele lay-outtips

Dompdf is geen volledige browser-engine. Het verwerkt CSS 2.1 goed en enkele CSS 3-eigenschappen, maar probeer daar geen Flexbox of Grid te gebruiken. De goede oude tabellen en floats zijn je beste keuze.

Twee dingen die je veel tijd zullen besparen:

1. Geef altijd codering op in je template: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Zonder dit zal Cyrillisch veranderen in vraagtekens.
2. Voor pagina-einden gebruik je de CSS-eigenschap page-break-after: always. Dit is de meest betrouwbare manier om de printer een nieuw vel te laten starten waar je het nodig hebt.

Is het de moeite waard om te gebruiken

laravel-dompdf is een werkpaard. Het is perfect voor het genereren van eenvoudige tot gemiddeld complexe documenten: facturen, serviceverslagen, eenvoudige overzichten.

Het belangrijkste voordeel is eenvoud. Je hoeft geen Node.js te installeren, Puppeteer, of server binaries te configureren. Alles werkt out-of-the-box op standaard PHP-hosting.

Echter, als je complexe JavaScript-grafieken moet renderen of je lay-out zwaar is met moderne CSS-trucs, kan Dompdf moeite hebben. In zulke gevallen is het beter om naar op Chromium gebaseerde tools te kijken. Maar voor 90% van de backend-ontwikkelaarstaken is dit pakket meer dan voldoende.

Het project leeft en wordt actief onderhouden (meer dan 7.000 sterren op GitHub) en wordt ondersteund door een van de meest bekende bijdragers in de Laravel-community. Als je het nog niet hebt geprobeerd — is het nu tijd om het te bookmarken.