Generisanje PDF iz HTML, opis osnovnih metoda DOMPDF

PDF - rasprostranjen međuplatformski format elektronskih dokumenata, koji više od dve decenije predstavlja opšti standard. Format je odličan za izvoz podataka sa sajta u vidu različitih šablona, na primer važnih informacija za korisnike, sertifikata, dokumenata, izveštaja, kupona, uputstava i drugih materijala.

Pregled popularnih biblioteka na PHP.

Na jeziku PHP napisano je mnogo biblioteka za generisanje PDF, a najpopularnije među njima su:

1. FPDF - potpuno besplatna biblioteka za kreiranje PDF dokumenata pomoću čistog PHP-a, bez upotrebe oznaka.  
   Minimalna verzija PHP 5.1.
   
   Glavne funkcije:
   - podrška za slike u formatima JPEG, PNG i GIF;
   - podešavanje zaglavlja i podnožja stranice;
   - automatski prelazak redova i prelomi stranica;
   - linkovi;
   - poravnavanje teksta;
   - promena boje elemenata dokumenta;
2. TCPDF - minimalna verzija PHP 5.3.
   
   Glavne funkcije biblioteke: 
   - podrška za slike JPEG, PNG i SVG po defaultu;
   - sve slike koje podržava GD i ImageMagick ekstenzije;
   - automatski prelazak redova;
   - prelomi stranica;
   - poravnavanje teksta;
   - režimi renderovanja teksta (popunjavanje, obrisivanje i obrezivanje);
   - automatsko numerisanje stranica i grupa stranica;
   - metode za XHTML + CSS, JavaScript;
3. HTML2PDF - API za pretvaranje gotove HTML oznake u PDF format. Na sajtu možete generisati dokument tako što ćete uneti link u odgovarajuće polje. Koristi biblioteku TCPDF.
   Za korišćenje je potrebna verzija PHP 5.6 ili novija, kao i instalirana ekstenzija mbstring ili gd. 
   
   Podržava sve potrebne funkcije za rad:
   - mogućnost podešavanja veličina stranica;
   - omogućava personalizaciju izgleda, menjajući fontove i boje, margine;
   - alati za dodavanje vodenih žigova u dokumente;
   - koristi enkripciju ili lozinke za zaštitu PDF fajlova od neovlašćenog štampanja i kopiranja;
4. DOMPDF - konverter HTML u PDF baziran na PHP-u. Ova biblioteka pretvara HTML i CSS (uključujući ugrađene stilove i spoljne stilove) u PDF dokumente.
   Za rad je potrebna PHP verzije 7.1 ili novija.
   
   Biblioteka podržava mnoge funkcije, kao što su:
   - CSS 2.1 i nekoliko svojstava CSS3, uključujući pravila @import, @media i @page;
   - većina HTML atributa;
   - podrška za slike gif, png (8, 24 i 32 bita sa alfa-kanalom), bmp i jpeg;
   - bez zavisnosti od spoljnih PDF biblioteka.

Primer generisanja PDF pomoću paketa DOMPDF

Inicijalizacija projekta

Da bismo inicijalizovali projekat, koristićemo komandu paketnog menadžera Composer - “composer init”, koju treba izvršiti putem terminala u korenu našeg projekta.

Posle standardne procedure odgovaranja na sva pitanja koja Composer postavlja, kreiraćemo fajl index.php u korenu projekta, gde će se nalaziti sva logika rada PDF generatora.

Takođe, kreiraćemo folder resources za skladištenje šablona sa HTML oznakom i folder storage za čuvanje rezultata.

Instalacija DOMPDF

1) COMPOSER - Biblioteku možete instalirati kao običan PHP paket pomoću komande paketnog menadžera, koja će instalirati sve potrebne zavisnosti. 

composer require dompdf/dompdf

2) GIT - možete klonirati repozitorijum ili jednostavno preuzeti biblioteku u obliku arhiva i staviti njen sadržaj u projekat.

git clone https://github.com/dompdf/dompdf/ .

U ovom slučaju, da biste koristili DOMPDF klase u PHP kodu, potrebno je da uključite fajl za automatsko učitavanje paketa, koji se nalazi na putanji dompdf/autoload.inc.php.

Princip rada sa DOMPDF

Kreiranje bilo kog PDF dokumenta dešava se u nekoliko koraka:

1. Podešavanje potrebnih parametara kao što su veličina i orijentacija papira, putanje do fajlova fontova i keša, podešavanje pristupa udaljenim resursima i drugo. 
2. Generisanje prikaza dokumenta. 
3. Pozivanje metode render za pokretanje samog procesa generisanja dokumenta.
4. Dobijanje rezultata generisanja dokumenta.

Konfiguracija DOMPDF

Osnovna klasa biblioteke je klasa Dompdf\Dompdf, koja sadrži metode za učitavanje HTML oznake, generisanje dokumenta i dobijanje rezultata.

U ulozi konfiguratora je klasa podešavanja Dompdf\Options, koju možete proslediti kao opcioni parametar konstruktora glavne klase Dompdf. 

U fajlu index.php uključujemo automatski učitavač koji je kreirao paketni menadžer i uvozimo potrebne klase:

require 'vendor/autoload.php';

use Dompdf\Dompdf;
use Dompdf\Options;

Glavne metode klase podešavanja:

setChroot - svi lokalni fajlovi koje dompdf otvara treba da se nalaze u katalogu koji je definisan ovom metodom. Nije preporučljivo postavljati ovu vrednost na “/”, jer to može omogućiti dompdf da čita bilo koje fajlove na serveru, što nije bezbedno. U šablonu, svi putevi do lokalnih fajlova treba da budu napisani u odnosu na navedeni direktorijum, u našem slučaju to je ranije kreirani folder resources.

setTempDir - putanja za čuvanje privremenih fajlova za učitavanje udaljenih slika. Navedeni katalog treba da bude dostupan za pisanje izvršnom procesu.

setIsRemoteEnabled - omogućavanje udaljenog pristupa fajlovima. Ako je ova opcija postavljena na true, DOMPDF će imati pristup slikama i CSS fajlovima sa udaljenih sajtova. Da bi ovaj metod radio, potrebno je da u PHP konfiguraciji parametar allow_url_fopen takođe bude postavljen na true.

setAllowedRemoteHosts - lista dozvoljenih udaljenih hostova. Svaka vrednost niza treba da bude ime hosta koje će se koristiti za filtriranje resursa koje možete učitati. Ako isRemoteEnabled ima vrednost FALSE, metod neće imati nikakav efekat. Po defaultu, vrednost je NULL, što dozvoljava bilo koji udaljeni host.

setPdfBackend - korišćeno proširenje za renderovanje PDF. Dozvoljene postavke: “PDFLib”, “CPDF”, “GD” i “auto”. “Auto” će proveriti prisustvo PDFLib proširenja i koristiti ga ako je pronađeno, inače će koristiti CPDF.

setFontDir - lokacija direktorijuma u kojem DOMPDF čuva fontove i metrike fontova. Ovaj direktorijum treba da postoji i bude dostupan za pisanje.

setDefaultPaperSize - veličina papira, za većinu zemalja po defaultu "a4".
Sve dozvoljene veličine možete videti u varijabli klase \Dompdf\Adapter\CPDF::PAPER_SIZES.

setDefaultPaperOrientation - orijentacija papira po defaultu. Dostupne opcije su portretna ili pejzažna.

setLogOutputFile - log-fajl za zapis sadržaja bafera izlaza posle izvršenja konverzije HTML u PDF, može biti koristan za debag informacije.

Primer konfiguracije Dompdf\Options()

define('ROOT', 'D:/OSPanel/domains/pdf/');

$options = new Options();
$options->setChroot(ROOT . 'resources/');
$options->setTempDir(ROOT . 'storage/tmp');
$options->setIsRemoteEnabled(true);
$options->setFontDir(ROOT . 'resources/fonts/');
$options->setDefaultPaperSize('a4');
$options->setDefaultPaperOrientation('portrait');

$dompdf = new Dompdf($options);

Primer generisanja PDF iz HTML

Metod klase-generisator prihvata već gotovu HTML oznaku u obliku stringa, tako da ovaj korak ne zavisi od biblioteke i za generisanje oznake može se koristiti bilo koji pogodan metod, bilo da je u pitanju šablon, string varijabla PHP-a ili baferisanje izlaza.

Koristićemo treću opciju i staviti sav sadržaj fajla resources/pdf-example.php u varijablu $html:

ob_start();
require 'resources/pdf-example.php';
$html = ob_get_contents();
ob_end_clean();

Korišćenje CSS-a u DOMPDF ima neka ograničenja:

• ćelije tabele ne mogu biti raspodeljene na više stranica, tj. red tabele mora stati na jednu stranicu;
• ne podržava CSS Flexbox;
• ne podržava CSS Grid;
• jedan primer DomPDF ne treba koristiti za renderovanje više od jednog HTML dokumenta, jer sačuvani artefakti renderovanja mogu uticati na buduće rezultate;
• korišćenje “neobrađenih” SVG-ova ne funkcioniše, morate ili kreirati link na spoljnji SVG fajl, ili koristiti DataURI na sledeći način:
  

  $html = '<img src="data:image/svg+xml;base64,' . base64_encode($svg) . '" ...>';​

Uključivanje fontova

DOMPDF po defaultu podržava samo sledeće fontove:

• Helvetica (Normal, Bold, Oblique, i BoldOblique varijante)
• Times (Normal, Bold, Oblique, i BoldOblique varijante)
• Symbol
• ZapfDingbats
• Courier (Normal, Bold, Oblique, i BoldOblique varijante)

Ovi fontovi podržavaju samo Windows ANSI kodiranje.

Da bi se u PDF fajlu prikazivali simboli koji nisu dostupni u Windows ANSI kodiranju, potrebno je navesti spoljašnji font koji će biti ugrađen u PDF fajl.

DOMPDF će ugraditi bilo koji navedeni font u PDF fajl, koji je prethodno učitan ili naveden u CSS pravilu @font-face.

Razmotrimo oba načina dodavanja spoljašnjih fontova.

1. Preuzimamo Google font Jost-Regular - https://fonts.google.com/specimen/Jost
   Postavljamo ga na putanju resources/fonts/Jost-Regular.ttf
   Zatim povezujemo preuzeti font preko pravila @font-face u %3Cstyle%3E tagove šablona:
   

   @font-face {
     font-family: "Jost-Regular";
     font-style: normal;
     font-weight: normal;
     src: url("resources/fonts/Jost-Regular.ttf") format('truetype');
   }

   
   Sada u CSS svojstvima možemo koristiti novi font: 
   

   body {
     font-family: 'Jost-Regular';
   }​

2. Direktno povezivanje fonta preko linka u tagove:
   

   <link href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap" rel="stylesheet" />​

   
   I zatim takođe navodimo porodično ime fonta u CSS svojstvima:
   

   body {
     font-family: 'Montserrat';
   }​

Primer HTML oznake dokumenta za DOMPDF

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap" rel="stylesheet" />
  <title>PDF Example</title>
  <style>
    @font-face {
      font-family: "Jost-Regular";
      font-style: normal;
      font-weight: normal;
      src: url("resources/fonts/Jost-Regular.ttf") format('truetype');
    }

    body {
      font-family: 'Montserrat';
    }

    table {
      font-family: 'Helvetica';
    }

    td, th {
      padding: 5px;
    }

    tr:nth-child(even) {
      background-color: #BFE7FF;
    }

    tr:nth-child(odd) {
      background-color: #F5F8FA;
    }

    img {
      width: 200px;
      height: 200px;
    }
  </style>
</head>

<body>
  <img src="https://ventiontech.com/cdn/shop/products/vention-black-vention-bluetooth-5-3-earphones-tws-true-wireless-headphones-usb-c-aac-sbc-stereo-sports-earbuds-with-mic-hi-fi-headset-35952785981606.jpg?v=1698226840" />
  <img src="resources/img/image.jpg" />
  <h1>PRODUCT #9823832</h1>
  <table>
    <tr>
      <td><b>Name</b></td>
      <td>Earphone</td>
    </tr>
    <tr>
      <td><b>Price</b></td>
      <td>$40.00</td>
    </tr>
    <tr>
      <td><b>Description</b></td>
      <td>Lorem ipsum dolor sit amet consectetur adipisicing elit. Consequatur quam excepturi omnis veniam odio saepe...</td>
    </tr>
    <tr>
      <td><b>Rate</b></td>
      <td>4.6</td>
    </tr>
  </table>
</body>
</html>

Renderovanje PDF dokumenta u PHP-u (DOMPDF)

Da biste učitali dobijenu oznaku, klasa Dompdf ima metodu loadHtml. Ona prihvata dva argumenta: HTML string za učitavanje i metod kodiranja. Po defaultu, drugi parametar je null, u tom slučaju se koristi kodiranje navedeno utagu.

Greške parsiranja čuvaju se u globalnom nizu $_dompdf_warnings.

Pored učitavanja stringa, dompdf možete koristiti metodu loadHtmlFile, koja je identična prethodnoj metodi, ali kao prvi parametar prihvata ime fajla ili URL za učitavanje.

Nakon što je oznaka učitana, treba pozvati metodu render koja obavlja pretvorbu HTML u PDF:

try {
    $dompdf->loadHtml($html);
    $dompdf->render();
} catch (Exception $e) {
    print_r($e->getMessage());
}

Dobijanje rezultata renderovanja PDF

DOMPDF biblioteka pruža zgodnu metodu za prikaz dobijenog rezultata direktno u pretraživaču - ova metoda se zove stream i prihvata dva parametra: ime izlaznog fajla i niz sa dodatnim opcijama.

Niz opcija dopušta dva ključa:

• compress - primeni kompresiju sadržaja toka. Po defaultu 1;
• attachment - postavlja za HTTP header "Content-Disposition:" vrednost "attachment", što uzrokuje da pretraživač otvori dijalog za preuzimanje. Po defaultu 1

Ako je potrebno sačuvati fajl na disku ili standardna metoda prikaza u pretraživaču ne odgovara, možete dobiti PDF dokument u obliku stringa metodom output, koja prihvata opcioni niz sa jednim ključem compress.

Zatim ovaj rezultat možete sačuvati u fajl na bilo koji način, na primer funkcijom file_put_contents:

// Prikazuje PDF dokument u pretraživaču
$dompdf->stream('pdf', ['Attachment' => 0]);
// Kreira PDF dokument na navedenoj putanji
file_put_contents('storage/results/' . time() . '.pdf', $pdf);

Primer PHP koda za generisanje PDF dokumenta

<?php

ini_set('allow_url_fopen', 'On');

require 'vendor/autoload.php';

use Dompdf\Dompdf;
use Dompdf\Options;

define('ROOT', 'D:/OSPanel/domains/pdf/');

$options = new Options();
$options->setChroot(ROOT . 'resources/');
$options->setTempDir(ROOT . 'storage/tmp');
$options->setIsRemoteEnabled(true);
$options->setFontDir(ROOT . 'resources/fonts/');
$options->setDefaultPaperSize('a4');
$options->setDefaultPaperOrientation('portrait');

$dompdf = new Dompdf($options);

ob_start();

require 'resources/pdf-example.php';
$html = ob_get_contents();

ob_end_clean();

try {
    $dompdf->loadHtml($html);
    $dompdf->render();
} catch (Exception $e) {
    print_r($e->getMessage());
}

// Prikazuje PDF dokument u pretraživaču
$dompdf->stream('pdf', ['Attachment' => 0]);

// Kreira PDF dokument na navedenoj putanji
file_put_contents('storage/results/' . time() . '.pdf', $pdf);