Uw eerste PDF

In het kort

In deze tutorial maakt u twee PDF-bestanden. Eerst schrijft u tekst rechtstreeks met de fluent Application Programming Interface (API) van core. Vervolgens rendert u een Hypertext Markup Language (HTML)-fragment met Cascading Style Sheets (CSS) naar een pagina. Aan het eind hebt u een werkend script dat u kunt aanpassen voor een echt document, plus koppelingen naar de framework- en servervarianten.

Beide benaderingen gebruiken dezelfde engine, dus wat u hier leert, geldt voor elke distributie.

Het diagram hieronder toont de twee manieren om een document op te stellen en de drie implementatieomgevingen die deze hergebruiken.

From your code to a PDF file

Voordat u begint

U hebt een geïnstalleerde core-engine nodig en een plek waar u een PHP-script kunt uitvoeren.

1. Controleer dat PHP 8.4 de actieve runtime is:

   php --version

2. Installeer de core-engine in uw project, als die nog niet aanwezig is:

   composer require nextpdf/core

3. Maak in de hoofdmap van het project een werkbestand met de naam first-pdf.php.

De 14 standaardlettertypen werken zonder configuratie

Het standaardlettertype voor de hoofdtekst valt terug op een van de 14 standaard Type 1-lettertypen die in ISO 32000-2 worden genoemd. Uw eerste document heeft geen lettertypebestanden nodig. Registreer aangepaste lettertypen later en sluit ze dan in wanneer het ontwerp daarom vraagt.

Een PDF genereren vanuit PHP

Begin met de fluent API. Document::createStandalone() retourneert een document dat u meteen kunt gebruiken. Voeg een pagina toe, stel een lettertype in, schrijf cellen en sla vervolgens op. Elke methode waarmee u het document opbouwt, retourneert het document, zodat de aanroepen van boven naar beneden leesbaar blijven.

1. Plaats deze code in first-pdf.php. Het script declareert strict types, laadt de autoloader en bouwt één pagina op:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Voer het script uit:

   php first-pdf.php

3. Controleer de uitvoer. Als het goed is, ziet u deze regel in de standaarduitvoer en staat er naast het script een nieuw bestand met de naam first-pdf.pdf:

   Wrote first-pdf.pdf

U hebt nu een geldig PDF 2.0-bestand gegenereerd. Open het in een viewer naar keuze om de kop en de regel eronder te zien.

save versus output

save() schrijft het document naar een bestandspad. Om de bytes in plaats daarvan naar een browser te streamen, roept u output() aan. Om de bytes in het geheugen vast te leggen, roept u getPdfData() aan. Een document is voor eenmalig gebruik. Zodra u een document hebt weggeschreven, maakt u voor het volgende document een nieuwe instantie aan in plaats van dezelfde opnieuw te gebruiken.

HTML naar PDF renderen

Cellen schrijven geeft u nauwkeurige controle. De meeste documenten zijn echter sneller te beschrijven in HTML en CSS. De core-engine bevat een HTML-pijplijn die volledig in PHP is geschreven. De methode writeHtml() rendert een fragment naar de huidige pagina. Daarbij gebruikt de engine geen browser of externe service.

1. Maak een tweede bestand, html-pdf.php, dat een HTML-fragment rendert:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. Voer het uit:

   php html-pdf.php

3. Bevestig de uitvoerregel en het nieuwe bestand:

   Wrote html-pdf.pdf

Behandel HTML-invoer als onbetrouwbaar

Wanneer HTML afkomstig is van een gebruiker, een formulier of een andere externe bron, valideer en saneer die invoer dan voordat u die doorgeeft aan writeHtml(). Het recipe HTML naar een PDF-pagina renderen behandelt de volledige beveiligingsaanpak en het streamingmodel.

De engine rendert een ondersteunde subset van HTML en CSS. Raadpleeg de CSS-ondersteuningsmatrix voordat u op een eigenschap vertrouwt. Wanneer een lay-out volledige browsergetrouwheid vereist, zoals flexbox, grid of webfonts, installeert u de Artisan-renderer en roept u in plaats daarvan writeHtmlChrome() aan. Die methode houdt tekst selecteerbaar.

Vanuit een framework-controller

Mogelijk draait uw applicatie al in een framework of via de server. Dezelfde twee aanroepen passen ook in die omgeving. De engine blijft hetzelfde; alleen de integratiecode verandert.

Laravel

De Pdf-facade levert voor elke aanroep een nieuw document op. PdfResponse maakt van een document een downloadrespons:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Zie de Laravel-quickstart.

Symfony

De bundle stelt een PdfFactory-service beschikbaar. Gebruik NextPDF\Symfony\Service\PdfFactory als type-hint in een controller, bouw een document op dezelfde manier op en retourneer het als HTTP-respons. Zie de Symfony-quickstart.

Server (REST)

Wanneer NextPDF Server draait, stuurt u een geordende operations-array met POST en retourneert de server de PDF-bytes:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Bij een 200-respons is de body de PDF. Zie de Connect-quickstart.

Volgende stappen

U hebt nu op drie manieren een PDF gegenereerd. Gebruik deze pagina’s om op elk daarvan verder te bouwen.

HTML naar een PDF-pagina renderen Het volledige HTML-recipe: ondersteunde elementen, het streamingmodel en de beveiligingshouding.

Kies uw pad Bepaal of u core, een framework of de server gebruikt en welke HTML-renderer u inzet.

Referentie voor de core-engine Elke methode, parameter en retourwaarde van Document.

Cookbook Taakgerichte recipeen voor styling, tabellen, paginering en meer.