Jak przestać zmagać się z generowaniem PDF w Laravel

Generowanie dokumentów PDF w internecie zawsze było sporym wyzwaniem. Pomyśl, ile razy próbowałeś idealnie rozmieścić fakturę czy raport, żeby odkryć, że czcionki się przesunęły, tabele rozjechały lub obrazy całkowicie zniknęły. Zazwyczaj wybór sprowadza się do złożonych narzędzi systemowych jak wkhtmltopdf, które wymagają konfiguracji serwera, lub płatnych usług chmurowych.

Jeśli pracujesz ze stackiem Laravel, istnieje sprawdzone rozwiązanie — pakiet laravel-dompdf autorstwa Barry'ego van den Heuvela. To nakładka na bibliotekę Dompdf, która pobiera Twój znajomy szablon Blade i konwertuje go do pliku PDF. Bez dodatkowych zależności serwerowych, tylko PHP.

Co siedzi pod maską

Projekt w zasadzie robi jedną rzecz: łączy możliwości Laravela z silnikiem Dompdf. Główna zaleta polega na tym, że nie musisz uczyć się nowej składni do tworzenia układu dokumentu. Tworzysz zwykły View, przekazujesz do niego dane, a pakiet zajmuje się renderowaniem.

Ciekawe jest to, że pakiet wspiera nie tylko standardowego Laravela, ale także Lumena. To przydatne, jeśli wyodrębniasz generowanie dokumentów do osobnego mikroserwisu.

Jak to działa w praktyce

Instalacja jest standardowa poprzez Composera:

composer require barryvdh/laravel-dompdf

Po tym masz dostęp do fasady Pdf. Najprostszy przykład tworzenia pliku wygląda tak:

use Barryvdh\DomPDF\Facade\Pdf;

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

Metoda loadView pobiera Twój plik Blade, przekazuje do niego zmienne i generuje obiekt, który możesz natychmiast wysłać użytkownikowi do pobrania lub po prostu wyświetlić w przeglądarce za pomocą stream().

Elastyczna konfiguracja stron

Często musisz zmienić orientację strony lub format papieru bezpośrednio w kodzie. Na przykład orientacja pozioma lepiej sprawdza się przy szerokich tabelach:

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

Przy okazji, jeśli chcesz zapisać plik na dysku zamiast serwować go użytkownikowi, metoda save() zrobi to jedną operacją.

Wsparcie PDF/A-3b i faktury elektroniczne

Nowsze wersje (3.x) dodały wsparcie dla standardu PDF/A-3b. Jest to kluczowe dla długoterminowej archiwizacji dokumentów. Ale jest pewne ale: ten standard wymaga osadzenia wszystkich czcionek w pliku. Standardowe Helvetica czy Times nie zadziałają — musisz użyć czegoś jak DejaVu Sans.

Dla tych, którzy pracują nad automatyzacją księgowości, pakiet wspiera teraz formaty Zugferd i Factur-X. To sytuacja, gdy plik XML z danymi faktury jest osadzony bezpośrednio w PDF. Wygląda to mniej więcej tak:

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

Kilka wskazówek dotyczących układu

Dompdf to nie pełny silnik przeglądarki. Dobrze radzi sobie z CSS 2.1 i niektórymi właściwościami CSS 3, ale nie próbuj używać tam Flexboxa ani Grid. Twoimi najlepszymi przyjaciółmi są stare, dobre tabele i floaty.

Dwie rzeczy, które zaoszczędzą Ci mnóstwo czasu:

1. Zawsze określaj kodowanie w swoim szablonie: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Bez tego cyrylica zamieni się w znaki zapytania.
2. W przypadku podziałów stron używaj właściwości CSS page-break-after: always. To najbardziej niezawodny sposób, aby drukarka zaczęła nowy arkusz tam, gdzie tego potrzebujesz.

Czy warto z tego korzystać

laravel-dompdf to prawdziwy koń roboczy. Idealnie nadaje się do generowania dokumentów o prostej do średniej złożoności: faktury, raporty serwisowe, proste zestawienia.

Główna zaleta to prostota. Nie musisz instalować Node.js, Puppeteer ani konfigurować binariów serwera. Wszystko działa out of the box na standardowym hostingu PHP.

Jednak jeśli musisz renderować złożone wykresy JavaScript lub Twój układ jest mocno obciążony nowoczesnymi sztuczkami CSS, Dompdf może sobie nie poradzić. W takich przypadkach lepiej rozejrzeć się za narzędziami opartymi na Chromium. Ale dla 90% zadań backend developera ten pakiet jest więcej niż wystarczający.

Projekt jest żywy i aktywnie rozwijany (ponad 7000 gwiazdek na GitHubie) i jest wspierany przez jednego z najbardziej znanych contributorów w społeczności Laravel. Jeśli jeszcze tego nie próbowałeś — teraz jest czas, żeby go dodać do zakładek.