HTML naar PDF, de makkelijke route

Tot nu toe heb je in dit traject pagina’s opgebouwd, één aanroep tegelijk. Veel documenten beschrijf je sneller als markup, het op tags gebaseerde tekstformaat dat voor webpagina’s wordt gebruikt. In deze tutorial geef je NextPDF wat Hypertext Markup Language (HTML), en de engine tekent de pagina voor je.

Wat je gaat bouwen

Een rapport van één pagina, gerenderd vanuit één enkele HTML-string. Het heeft een gekleurde kop, een korte paragraaf en een tabel met een totaalrij. Je maakt het op met Cascading Style Sheets (CSS), de regeltaal die bepaalt hoe markup eruitziet. In de eerdere tutorials gebruikte je de vloeiende Application Programming Interface (API), de aaneengeschakelde methodeaanroepen. Hier beschrijf je de opmaak in plaats daarvan met markup, en dezelfde engine rendert het.

Stap 1: Render een opgemaakt rapport vanuit HTML

Maak een bestand met de naam 01-html.php in je projectmap, naast vendor. Plak dit volledige script erin:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

Voer het script uit vanuit de projectmap:

php 01-html.php

Je zou één regel uitvoer moeten zien:

Wrote out/reading-report.pdf

Open out/reading-report.pdf in een willekeurige Portable Document Format (PDF)-viewer. De kop is donkerblauw, en de koprij van de tabel is met dezelfde kleur gevuld.

Wat er zojuist gebeurde

@mkdir(__DIR__ . '/out'); maakt de uitvoermap aan. Het @-teken verbergt de waarschuwing wanneer de map al bestaat, zodat herhaalde runs stil blijven.
Document::createStandalone(), setTitle() en addPage() werken precies zoals in de eerdere tutorials. Overstappen op markup verandert niets aan het opzetten van het document.
writeHtml() leest je string één keer, van boven naar beneden, en tekent elk element op de huidige positie. Koppen en paragrafen worden opgemaakte tekst. De tabel wordt omgezet in opgemeten rijen met omrande cellen.
De inline style-attributen bevatten de CSS. De engine begrijpt veelvoorkomende eigenschappen zoals color, background-color, text-align en width.
Er komt geen browser en geen extra software aan te pas. De pijplijn is gewone PHP binnen de engine, dus het script draait overal waar je Composer-installatie draait.

De engine ondersteunt een praktische subset van HTML en CSS, niet alles wat een browser accepteert. Alles buiten die subset wordt stilletjes overgeslagen in plaats van dat er een fout optreedt. De CSS-ondersteuningsmatrix legt precies vast wat er wordt gedekt. Voor een diepere doorloop van deze pijplijn, zie HTML naar een PDF-pagina renderen.

Wanneer gebruik je HTML en wanneer de vloeiende API

Beide routes draaien op dezelfde engine, dus kies degene die bij het document past.

Kies writeHtml() wanneer het document leest als een webpagina: koppen, paragrafen, lijsten en tabellen. Markup is sneller te schrijven en makkelijker te bewerken voor teamgenoten.
Kies de vloeiende API wanneer je exacte plaatsing nodig hebt, zoals vaste posities of nauwkeurig opgemeten cellen. Markup geeft je flow; de vloeiende aanroepen geven je controle.
Controleer de CSS-ondersteuningsmatrix voordat je op een eigenschap vertrouwt. Wanneer een stijl niet wordt gedekt, bouw dat deel dan met vloeiende aanroepen.

De veiligheidsgrens

Echte HTML komt vaak van buiten je code, bijvoorbeeld uit een formulier of een database. Behandel het als niet-vertrouwde invoer en valideer of schoon het op voordat je rendert. Standaard voert de ingebouwde pijplijn geen scripts uit en haalt geen externe bronnen op. Die standaard houdt de renderer behoudend, zelfs wanneer de markup dat niet is. Als je rendering-opties op browserniveau nodig hebt, zie Kies je pad.

Als er iets misging

Failed to open stream: No such file or directory betekent meestal dat het script vendor/autoload.php niet kan vinden. Voer het uit vanuit de map waar je Composer hebt uitgevoerd.
Een ontbrekende stijl is meestal een eigenschap buiten de ondersteunde subset. De engine slaat over wat hij niet ondersteunt in plaats van te falen. Vergelijk je markup met de CSS-ondersteuningsmatrix.
Een uitzondering tijdens het renderen benoemt het exacte probleem. Zoek het op in de referentie rendering- en invoer/uitvoerfouten.

Begin voor al het andere met de probleemoplossingsgids.

Je kunt nu documenten opbouwen aanroep voor aanroep en vanuit markup. Rond het traject af met Waar je hierna heen gaat. Het brengt de cookbook, de referentie en de gidsen in kaart die je na dit traject gaat gebruiken.