Domů

PHP-generujeme PDF

Zhlédnutí: 7303

Napsal filbar

Úterý, 18 září 2007

Aktualizováno ( Čtvrtek, 13 září 2007 )

Pro generování PDF v PHP můžeme využít, buď existujících PHP funkcí, nebo dvou vynikajících tříd, které jsou pro tento úkol mnohem lepším řešením a na jednu z nich se v tomto článku zaměříme.

První z nich, ač je výkonnější, je již delší dobu neudržovaná a mezi její další nevýhody patří, že nepodporuje české diakritické znaky. Nachází se na adrese http://www.ros.co.nz/pdf/. Její kvalita tkví hlavně v generování různých grafických obrazců. V tomto návodu se však budeme zabývat moderní alternativou, která plně podporuje UTF-8 a tím taky diakritiku. Třída se jmenuje tcpdf a její domovskou stránku nalezneme zde . Je postavena na projektu fpdf.

Stažení a instalace

Ke stažení jsou k dispozici dva balíčky. Jeden pro php4 a druhý pro php5. V době psaní článku byla nejaktuálnější verze 1.53.0. Po rozbalení zip archivu se vytvoří nová složka, kterou celou přeneseme na odpovídající místo na web serveru. Pokud nám záleží na zabraném místě lze odstranit podadresář doc a soubory test* a utf8text.txt, které slouží pouze pro prezentaci možností generátoru PDF.

Do všech souborů, které mají na starost obsluhu generování PDF je nutné zaincludovat soubor tcpdf.php a config/lang/eng.php, případně jiný, pokud si jej vytvoříme. Jelikož se zde nachází pouze jeden textový řetězec k přeložení(page), tak lze použít i originální soubor. Jinak v adresáři config/lang/ zkopírujeme soubor eng.php třeba na czech.php a přeložíme již zmíněný řetězec. Tento soubor pak zaincludujeme do stránky.

Generování PDF

Před začátkem generování PDF je nutné nastavit ještě dvě cesty K_PATH_MAIN a K_PATH_URL, které označují umístění souborů tcpdf. Nastavení se děje pomocí příkazů define:

 
define('K_TCPDF_EXTERNAL_CONFIG', true);
define ("K_PATH_MAIN", $absolute_path."/includes/tcpdf/");
define ("K_PATH_URL", $live_site."/includes/tcpdf/");

První definicí říkáme, že se má použít externí konfigurace, tedy ne ta, ze souboru config/tcpdf_config.php. Druhá definice určuje cestu na serveru k souborům tcpdf a poslední určíme, jak se k nim lze dostat přes URL, neboli adresu, kterou zadáváme do prohlížeče. Konfigurace je trošku hloupěji udělaná a tak, jakmile určíme, že se má používat externí konfigurace, musíme nadefinovat všechny volby. To zajistíme dopsáním následujících řádků:

 
define ("FPDF_FONTPATH", K_PATH_MAIN."fonts/");
define ("K_PATH_CACHE", K_PATH_MAIN."cache/");
define ("K_PATH_URL_CACHE", K_PATH_URL."cache/");
define ("K_PATH_IMAGES", K_PATH_MAIN."images/");
define ("K_BLANK_IMAGE", K_PATH_IMAGES."_blank.png");
define ("PDF_PAGE_FORMAT", "A4");
define ("PDF_PAGE_ORIENTATION", "P");
define ("PDF_CREATOR", "TCPDF");
define ("PDF_AUTHOR", "TCPDF");
define ("PDF_UNIT", "mm");
define ("PDF_MARGIN_HEADER", 5);
define ("PDF_MARGIN_FOOTER", 10);
define ("PDF_MARGIN_TOP", 27);
define ("PDF_MARGIN_BOTTOM", 25);
define ("PDF_MARGIN_LEFT", 15);
define ("PDF_MARGIN_RIGHT", 15);
define ("PDF_FONT_NAME_MAIN", "freeserif"); //vera
define ("PDF_FONT_SIZE_MAIN", 10);
define ("PDF_FONT_NAME_DATA", "freeserif"); //verase
define ("PDF_FONT_SIZE_DATA", 8);
define ("PDF_IMAGE_SCALE_RATIO", 4);
define("HEAD_MAGNIFICATION", 1.1);
define("K_CELL_HEIGHT_RATIO", 1.25);
define("K_TITLE_MAGNIFICATION", 1.3);
define("K_SMALL_RATIO", 2/3);

Teď již konečně lze začít tvořit PDF soubor. Nejprve je nutné si vytvořit objekt, přes který se budeme na metody pdf třídy odvolávat. Mezi její parametry patří popořadě orientace stránky(P-na výšku-výchozí, L-na šířku), jednotky pro umísťování textu na stránku(výchozí mm), formát stránky(A4-výchozí,A5,...), booleovská hodnota jestli se použije kódování unicode(výchozí je true) a případně znaková sada(jako výchozí je definována UTF-8):

 
$pdf = new TCPDF(PDF_PAGE_ORIENTATION, PDF_UNIT, PDF_PAGE_FORMAT, true);

Hlavička

Jak si lze všimnout zde s výhodou využíváme dříve definovaných konstant. Pokud je nepotřebujeme, není nutná, ani jejich definice. Totéž platí i o ostatních konstantách, ale způsob s jejich definicí je programátorsky čistší. Další metoda slouží pro nastavení okrajů generovaného dokumentu. V parametrech jsou uvedené okraje vlevo, nahoře, vpravo a dole:

 
$pdf->SetMargins(PDF_MARGIN_LEFT, PDF_MARGIN_TOP, PDF_MARGIN_RIGHT);

S okraji stránky souvisí i umístění případného záhlaví, které zařizuje metoda SetHeaderData(), která očekává umístění loga, jeho šířku v mm, titulek a řetězec, který se má v záhlaví objevit. Jestliže něco z toho nechceme do dokumentu umísťovat stačí uvedení konstanty NULL, jako v následujícím příkladu:

 
$pdf->SetHeaderData(NULL,NULL, Testovací dokument, NULL);

Do zápatí text ručně umísťovat nelze. Zápatí slouží pouze k číslování stran. Velikost záhlaví/zápatí se nastavuje pomocí metod SetHeaderMargin()/setFooterMargin(). Lze také určit písmo, které použije pro jejich vysázení. To zajistíme metodami setHeaderFont()/setFooterFont(), které obě v parametru očekávají pole obsahující jméno písma, jeho styl(B-tučné, I-kurzíva a U-podtržené; konstanty lze samozřejmě kombinovat) a nakonec velikost. Všechna dostupná písma najdeme v adresáři fonts:

 
$pdf->setHeaderFont(Array(PDF_FONT_NAME_MAIN, '', PDF_FONT_SIZE_MAIN));
$pdf->setFooterFont(Array(PDF_FONT_NAME_DATA, '', PDF_FONT_SIZE_DATA));

Na závěr hlavičky ještě zinicializujeme značku pro počet stran touto metodou:

 
$pdf->AliasNbPages();

Hlavní dokument

Vložení textu

Abychom mohli začít tvořit hlavní dokument, je nutné nejprve přidat první stránku metodou AddPage().Text to stránky vložíme pomocí metody Write(), která jako parametry očekává velikost řádku, text k zapsání, a dva nepovinné argumenty označující jestli má text pracovat jako odkaz. Jestliže uvedeme prázdnou hodnotu bude se jednat o normální text. V případě zapsání adresy se bude jednat o odkaz. Poslední parametr určuje, jestli se má pozadí vyplnit barvou nastavenou metodou SetFillColor(), ke které se dostaneme později. Vložení textu může vypadat např. takto:

 
$pdf->Write(6,$text, "http://www.linpro.cz", 1);

V příkladu má řádek velikost 6, zapíše se text uložený v proměnné $text, celý bude fungovat jako odkaz na tento portál a jeho bude vyplňovat nějaká barva(hodnota 1 v posledním parametru;pro bílé pozadí zadáme 0). Daleko výkonnější je writeHTML(), která přijímá první a třetí parametr totožný s druhým a čtvrtým parametrem předchozí metody. Třetí parametr určuje jestli se má za text vložit prázdný řádek. Jako text lze použít kompletně HTML formátovaný text včetně obrázků(ve formátu jpg a png), tabulek a nadpisů. Všechno se převede do PDF, pouze u obrázku se nezachová obtékání. Text skončí před obrázkem a pokračuje až za ním:

 
$pdf->writeHTML($text, true, 0);

Buňky, tabulky

HTML text do rámečku na určenou pozici vložíme metodou writeHTMLCell(), která přebírá čtyři povinné a čtyři nepovinné parametry. Mezi povinné parametry patří minimální šířka a výška ,x-ová a y-ová souřadnice levého horního rohu. Abychom určení souřadnic neměli tak moc složité existují metody getX() a getY(), které vrátí aktuální pozici. V dalším nepovinném parametru zadáváme HTML text, který se má v rámečku zobrazit. Šestý parametr je zodpovědný za nastavení rámečku kolem buňky a může obsahovat buď číslo 0(rámeček se nezobrazí), nebo 1(zobrazení rámečku). Druhou variantou je zadání stran, kolem kterých se rámeček vykreslí. Možné varianty jsou L(vlevo), T(nahoře), R(vpravo) a B(dole). Předposlední parametr nastavuje obtékání a lze mu přiřadit hodnoty od 0 do 2. 0 znamená, že pozice pro vkládání textu se nastaví hned za buňku, při jedničce text pokračuje na začátku nového řádku a při hodnotě 2 pod buňkou. Osobně se mi nepodařilo přijít na rozdíl mezi hodnotou jedna a dvě. Poslední parametr řídí jestli chceme rámeček průhledný(0), nebo vybarvený(1). Barva se nastavuje metodou SetFillColor().

 
$pdf->writeHTMLCell(60, 0, 0, $pdf->getY(), $text, 1, 0, 0);

Ekvivalent pro vkládání čistého textu nese název Cell(). Obsahuje však jednu výhodu. Není nutné nijak zjišťovat umístění. Použije se aktuální pozice. Zadává se pouze výška a šířka buňky. Dále text k zobrazení, rámeček a obtékání, které jsou stejné jako u předchozí metody. Nově je možné určit zarovnání: L(doleva), C(na střed), R(doprava) a J(do bloku). Následuje určení průhlednosti a případný text odkazu:

 
$pdf->Cell(20,40,"$text",1,1,'J');

Jestliže chceme v buňce používat zalomení řádku, využijeme metody MultiCell(), která přebírá první čtyři parametry stejné jako Cell(). Další parametry jsou však v jiném pořadí, konkrétně zarovnání, průhlednost a obtékání.

Pomocí těchto tří metod lze vytvořit i tabulky. Jestliže se má buňka nacházet na stejném řádku jako ta předchozí do parametru obtékání zadáme 0, pro vložení buňky na nový řádek zapíšeme 1. Mezi výhody takto vytvořené tabulky patří různá šířka sloupců i výška řádků..

Formátování

Platnost jedné formátovací metody platí až do výskytu jiné metody nastavující formátování. Možná to z tohoto popisu vypadá trošku zmateně a tak to vysvětlím raději na příkladu. Pokud nejprve nastavíme velikost písma např. na 14 a poté zadáme nějakou metodu pro zápis text a následně změníme velikost písma na 8 a zapíšeme další text, bude ten první bude mít velikost 14 a druhý 8, protože druhým nastavením velikost jsme to první přepsali, což je velmi výhodné. Totéž platí i pro následující metody.

Kompletní formát písma zadáme metodou SetFont(). Jako parametry přebírá název písma, jeho styl a velikost. Samotnou velikost určíme pomocí SetFontSize(). Barva pozadí se nastavuje přes SetFillColor(), která přebírá barvu ve formátu RGB a jestli má tuto barvu také uložit do proměnné $storeprev, k budoucímu použití. Stejně obarvíme i písmo metodou SetTextColor(). Barvu rámečků a ostatní grafiky nastavíme pomocí SetDrawColor(), v parametrech se nachází pouze RGB určení barvy.

Rozvržení stránky určuje parametr AddPage(). Pro svislou stránku zadáme P, pro stránku naležato L. Jakmile tuto metodu použijeme ukončí se logicky předxchozí stránka a vešerý text pokračuje na stránce následující, z čehož vyplývá, že jí lze využít i pro ruční zalomení známe z klasických textových editorů.

Grafika

Tato třída podporuje i vkládání obrázků ve formátu jpg a png. Jejich vložení zajistí metoda vhodně pojmenovan Image() s třemi povinnými a 4 nepovinnými argumenty. Povinné argumenty představují cestu k obrázku a souřadnice jeho levého horního rohu. Jestliže chceme obrázek zmenšit zadáme jeho novou velikot do následujících dvou parametrů. Když zadáme typ obrázku(JPG, JPEG, nebo PNG) nepoužije se automatické detekce podle jeho přípony. Nakonec ještě lze nastavit odkaz, na který má obrázek vést.

Někdu se může hodit i vytvoření linky, k čemuž můžeme použít metody pojmenované Line(). Do jejich parametrů logicky zadáme souřadnice prvního a druhého bodu, které má spojovat. Její barvu určíme pomocí dříve zmiňované SetDrawColor().

Posledním grafickým prvkem, který třída dokáže vytvořit je obdélník. Jako u buněk přebírá souřadnice levého horného rohu a proporce. Posledním parametr určí podle kombinace písmen D a F, jestli se vykreslí rámeček(D) a/nebo výplň(F):

 
$pdf->Rect($pdf->getX(), $pdf->getY(), 10 , 20, "DF");

Odkazy

Ke vkládání odkazů slouží především dřívější metody, které nabízejí jako jeden z parametrů adresu, na kterou má vést odkaz. Přesto, pokud by toto nestačilo, je k dispozici ještě možnost, jak vytvořit odkaz na zadaných souřadnicích. Pro vytvoření tohoto typu odkazů je nutné použít tří metod. V první z nich AddLink() vytvoříme idenfikátor odkazu, který využijeme v následujících dvou metodách. Druhou využijeme k zadání na jakou stránku a jaké souřadnice na ní má odkaz vést. Do jejich parametrů zadáme identifikátor odkazu, souřadnice a stránku. Konečně v poslední metodě jménem Link() určíme oblast, která má sloužit jako odkaz. V parametrech uvedeme obvyklé souřadnice levého horního rohu, šířku a výšku a nakonec identifikátor odkazu:

 
$link=$pdf->AddLink();
$pdf->SetLink($link, 0, 2);
$pdf->Link(0,$pdf->getY(),20,30,$link);

Normální textový odkaz do textu vložíme metodou addHtmlLink(), do jejíchž parametrů uvedeme adresu, na kterou má link odkazovat, text který se má zobrazit jako odkaz a nakonec průhlednost pozadí.

Vlastnosti dokumentu

Pod pojmem vlastnosti dokumentu si můžeme představit jméno autora, klíčová slova, atd. I tyhle věci lze nastavit pomocí odpovídajících metod. Hlavní údaje bezesporu jsou název dokumentu(SetTitle()), jeho autor(SetAuthor()), aplikaci, která PDF vytvořila(SetCreator()), o čem dokument pojednává(SetSubject()) a nakonec klíčová slova dokumentu(SetKeywords()). Všechny tyto metody přebírají pouze jeden parametr, kterým je textový řetězec.

Generujeme

V této chvíli máme celý PDF dokument hotový. Zbývá poslední příkaz, který zajistí jeho vygenerování a případné uložení. Tímto příkazem je Output(), který přebírá dva nepovinné parametry. Druhý parametr určuje, kam se dokument vygeneruje. Možné jsou čtyři varianty: I-soubor se otevře v pluginu prohlížeče; D-otevření v prohlížeči, ale je vynucen dialog pro uložení na disk pod jménem zadaným v prním parametru; F-soubor je uložen na serveru pod jménem získaným z prvního parametru. Posledním možným výstupem je textový řetězec představovaný parametrem S.

Závěr

Tím bychom měli mít kompletní PDF dokument hotový a připravený k použití. Přesto, že jsem zde předvedl hodně z možností TCPDF existují ještě skulinky, které se můžete dovědět navíc v dokumentaci. Co se týče této třídy, myslím, si že základní požadavky na tvorbu PDF z aplikací PHP určitě uspokojí. Sice se nejedná o žádný ekvivalent plného Acrobatu, ale toho by se stejné v prostředí PHP nebyužilo. O kvalitách tohoto projektu mimo jiné svědčí i to, že si jej vybral velmi dobrý redakční systém Joomla pro novou verzi 1.5.