NextPDF installeren en je eerste PDF genereren

NextPDF is een PHP-library die PDF-bestanden (Portable Document Format) genereert. In deze tutorial installeer je het in een lege map en render je je eerste document van één pagina. Je hebt een terminal nodig en ongeveer tien minuten.

Wat je gaat bouwen

Je bouwt een klein project met één script, 01-hello.php. Het script rendert één pagina met een vetgedrukte titelregel en één alinea. Het slaat het resultaat op als out/hello.pdf. Onderweg leer je twee commando’s waarmee je bevestigt dat je installatie gezond is.

Deze pagina behandelt één installatiepad: een lege map plus het engine-package. Er bestaan andere paden, zoals framework-adapters, browsergebaseerde renderers en de Python-client. Die vind je in Installatie en Kies je pad. Vandaag heb je ze niet nodig.

Stap 1: Maak een project en installeer NextPDF

Composer is de package manager voor PHP. Het downloadt libraries naar je project en genereert een autoloader. Een autoloader is een klein PHP-bestand dat library-classes voor je opzoekt, zodat je nooit lange lijsten met includes hoeft te schrijven.

Open een terminal en voer deze drie commando’s uit:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer toont voortgang terwijl het packages oplost en downloadt. De exacte regels hangen af van je Composer-versie en je lokale cache. Een geslaagde installatie eindigt zonder foutmeldingen en ziet er ongeveer zo uit:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Wat er zojuist gebeurde

Composer heeft drie dingen in je map aangemaakt. composer.json legt vast dat je project afhankelijk is van de engine. composer.lock zet de exacte geïnstalleerde versie vast, zodat een latere installatie dezelfde code oplost. De map vendor/ bevat de gedownloade packages, waaronder vendor/autoload.php. Je script laadt dat ene bestand en elke engine-class wordt beschikbaar.

Composer heeft tijdens de installatie ook je PHP-setup gecontroleerd. De engine geeft aan welke PHP-extensies hij nodig heeft. Extensies zijn optionele modules die in PHP zijn ingebouwd. Als er een ontbreekt, stopt Composer en noemt die, in plaats van je met een kapotte installatie achter te laten.

Stap 2: Render je eerste PDF

Maak een bestand met de naam 01-hello.php naast composer.json. Plak dit volledige programma erin:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

Voer het uit:

php 01-hello.php

Je zou precies één regel moeten zien:

Wrote out/hello.pdf

Open out/hello.pdf in een willekeurige PDF-viewer. Je ziet de vetgedrukte titelregel met de alinea eronder, en de meeste viewers tonen “Hello from NextPDF” in hun venstertitel.

Wat er zojuist gebeurde

Loop het script van boven naar beneden door:

require laadt de Composer-autoloader, zodat de Document-class oplosbaar wordt.
@mkdir maakt de map out/ aan. De voorafgaande @ houdt het script stil wanneer de map al bestaat, zodat je het opnieuw kunt uitvoeren.
Document::createStandalone() retourneert een nieuw document. Het is gemaakt voor korte command-line scripts precies zoals dit.
setTitle() stelt de documenttitel in, die viewers in de venstertitel tonen.
addPage() voegt één lege pagina toe en plaatst de cursor linksboven.
setFont() kiest een lettertypefamilie, een stijl en een grootte in punten. Punten zijn de standaardeenheid voor lettergroottes in drukwerk. 'B' betekent vet en '' betekent normaal. De familie met de naam helvetica is ingebouwd, dus je hebt geen lettertypebestanden nodig.
cell() schrijft één tekstregel op de cursorpositie. Een breedte van 0 betekent “uitrekken tot de rechtermarge”. newLine: true verplaatst de cursor daarna naar beneden, zoals bij het indrukken van Enter.
save() bouwt de voltooide PDF en schrijft die naar schijf.

Eén document levert één bestand op. Wanneer je een tweede PDF nodig hebt, maak dan een nieuw document in plaats van het oude opnieuw te gebruiken.

Stap 3: Verifieer je installatie

Twee snelle controles bevestigen dat deze installatie ook na dit ene script blijft werken.

Maak eerst een lijst van de extensies die je PHP bevat:

php -m

Zoek in de lijst naar curl, gd, intl, mbstring, openssl en zlib. De engine steunt op deze zes. Composer heeft ze in Stap 1 al gecontroleerd, dus ze zouden allemaal moeten verschijnen.

Voer als tweede de eigen gezondheidscontrole van de engine uit:

vendor/bin/nextpdf doctor

Roep op Windows in plaats daarvan vendor\bin\nextpdf doctor aan. Het commando inspecteert je PHP-versie, extensies, tijdelijke map en configuratie. Elke controle drukt [OK], [WARN] of [FAIL] af, gevolgd door één algemeen oordeel.

Wat er zojuist gebeurde

Lees eerst het Extensions-blok. Zes [OK]-regels met de namen curl, gd, intl, mbstring, openssl en zlib betekenen dat je installatie klaar is voor elke tutorial die volgt.

Het rapport toont ook de mogelijkheden van de engine. Bij de gratis Core-installatie tonen de mogelijkheden die bij de commerciële packages horen [FAIL] met een bericht dat het package noemt dat ze levert. Dat is hier te verwachten, en het kan het algemene oordeel op UNHEALTHY zetten, ook al is je Core-setup in orde. Voor deze tutorials is het Extensions-blok het signaal dat telt.

Als er iets misging

Vergelijk je symptoom eerst met deze veelvoorkomende gevallen:

composer: command not found betekent dat Composer ontbreekt of niet op je PATH staat. Installeer het via getcomposer.org en herhaal daarna Stap 1.
Failed opening required '.../vendor/autoload.php' betekent dat het script buiten de projectmap draaide, of dat de installatie niet is voltooid. Ga naar de map uit Stap 1 en voer composer install uit.
Als Composer tijdens Stap 1 stopt en een ontbrekende PHP-extensie noemt, schakel die extensie dan in in je php.ini. Bevestig dit met php -m en herhaal daarna de installatie.
Een [FAIL]-regel in het Extensions-blok van de doctor noemt een ontbrekende PHP-extensie. Schakel die in in php.ini, bevestig met php -m en voer de doctor opnieuw uit. [FAIL]-regels voor mogelijkheden die een commercieel package noemen, zijn te verwachten bij de Core-installatie en vereisen hier geen actie.

Begin voor al het andere met de kennisbank voor probleemoplossing. Als een script een exception gooit, zoek dan de class op in de foutreferentie; de meeste beginnersfouten staan onder algemene fouten.

Verder

Je hebt een werkende installatie en je eerste gerenderde bestand. Ga verder met Tekst, lettertypen en paginabasis om paginaformaten, ingebouwde lettertypen, kleuren en uitlijning te bepalen.