Ihr erstes PDF

Auf einen Blick

In diesem Tutorial erzeugen Sie zwei PDF-Dateien. Für die erste Datei schreiben Sie Text direkt mit der fluenten Core-API (Application Programming Interface). Für die zweite rendern Sie ein Fragment aus HyperText Markup Language (HTML) und Cascading Style Sheets (CSS) in eine Seite. Am Ende haben Sie ein funktionierendes Skript, das Sie für ein echtes Dokument anpassen können. Außerdem wissen Sie, wo die Framework-Varianten und die Server-Variante zu finden sind.

Beide Ansätze laufen auf derselben Engine. Was du hier lernst, überträgt sich also auf jede Distribution.

Das Diagramm unten zeigt die zwei Authoring-Ansätze und die drei Deployment-Oberflächen, die sie wiederverwenden.

From your code to a PDF file

Bevor Sie beginnen

Sie benötigen zwei Dinge: die installierte Core-Engine und einen Ort, an dem Sie ein PHP-Skript ausführen können.

1. Stellen Sie sicher, dass PHP 8.4 die aktive Laufzeitumgebung ist:

   php --version

2. Installieren Sie die Core-Engine in Ihrem Projekt, falls sie noch nicht vorhanden ist:

   composer require nextpdf/core

3. Legen Sie im Projektwurzelverzeichnis eine Arbeitsdatei mit dem Namen first-pdf.php an.

Die 14 Standardschriften funktionieren ohne zusätzliche Einrichtung

Die voreingestellte Textschrift wird auf eine der 14 Standard-Type-1-Schriften abgebildet, die in ISO 32000-2 benannt sind. Ihr erstes Dokument benötigt also keine Schriftdateien. Eigene Schriften registrieren und betten Sie später ein, sobald ein Design sie erfordert.

Ein PDF aus PHP erzeugen

Beginnen Sie mit der fluenten API. Document::createStandalone() liefert ein einsatzbereites Dokument zurück. Sie fügen eine Seite hinzu, setzen eine Schrift, schreiben Zellen und speichern anschließend. Jede Authoring-Methode gibt das Dokument zurück, sodass sich die Aufrufe von oben nach unten lesen.

1. Fügen Sie diesen Code in first-pdf.php ein. Das Skript deklariert strikte Typen, lädt den Autoloader und baut ein einseitiges Dokument auf:

   <?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. Führen Sie das Skript aus:

   php first-pdf.php

3. Prüfen Sie die Ausgabe. Sie sollten diese Zeile auf der Standardausgabe sehen und neben dem Skript eine neue Datei mit dem Namen first-pdf.pdf:

   Wrote first-pdf.pdf

Sie haben jetzt eine gültige PDF 2.0-Datei erzeugt. Öffnen Sie sie in einem beliebigen PDF-Viewer, und Sie sehen die Überschrift mit der darunterliegenden Zeile.

save versus output

save() schreibt das Dokument an einen Dateipfad. Um die Bytes stattdessen an einen Browser zu streamen, rufen Sie output() auf. Um die Bytes im Speicher festzuhalten, rufen Sie getPdfData() auf. Ein Dokument ist für die einmalige Verwendung gedacht — sobald Sie eines geschrieben haben, erstellen Sie für das nächste Dokument eine frische Instanz, statt es wiederzuverwenden.

HTML in PDF rendern

Das Schreiben von Zellen gibt Ihnen präzise Kontrolle. Die meisten Dokumente lassen sich jedoch schneller als HTML und CSS beschreiben. Die Core-Engine enthält eine reine PHP-HTML-Pipeline. Die Methode writeHtml() rendert ein Fragment in die aktuelle Seite. Sie verwendet keinen Browser und keinen externen Dienst.

1. Erstellen Sie eine zweite Datei, html-pdf.php, die ein 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. Führen Sie die Datei aus:

   php html-pdf.php

3. Prüfen Sie die Ausgabezeile und die neue Datei:

   Wrote html-pdf.pdf

Behandeln Sie HTML-Eingaben als nicht vertrauenswürdig

Wenn das HTML von einem Nutzer, einem Formular oder einer beliebigen externen Quelle stammt, validieren und bereinigen Sie es, bevor Sie es an writeHtml() übergeben. Das Recipe HTML in eine PDF-Seite rendern behandelt die vollständige Sicherheitslage und das Streaming-Modell.

Die Engine rendert eine unterstützte Teilmenge von HTML und CSS. Bevor Sie sich auf eine Eigenschaft verlassen, prüfen Sie sie anhand der CSS-Support-Matrix. Wenn ein Layout vollständige Browser-Treue erfordert — zum Beispiel Flexbox, Grid oder Web-Schriften — installieren Sie den Artisan-Renderer und rufen stattdessen writeHtmlChrome() auf. Diese Methode hält den Text auswählbar.

Aus einem Framework-Controller

Ihre Anwendung läuft möglicherweise bereits auf einem Framework oder als Server. Dieselben zwei Aufrufe lassen sich in diese Umgebung übertragen. Die Engine bleibt identisch, nur die Verdrahtung ändert sich.

Laravel

Die Pdf-Fassade löst bei jedem Aufruf ein frisches Dokument auf. PdfResponse wandelt ein Dokument in eine Download-Antwort um:

<?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');
    }
}

Siehe den Laravel-Schnellstart.

Symfony

Das Bundle stellt einen PdfFactory-Dienst bereit. Verwenden Sie NextPDF\Symfony\Service\PdfFactory als Type Hint in einem Controller, bauen Sie ein Dokument auf dieselbe Weise auf und geben Sie es dann als HTTP-Antwort zurück. Siehe den Symfony-Schnellstart.

Server (REST)

Wenn NextPDF Server läuft, senden Sie ein geordnetes Operations-Array per POST, und der Server liefert die PDF-Bytes zurück:

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

Bei einer 200-Antwort enthält der Body das PDF. Siehe den Connect-Schnellstart.

Nächste Schritte

Sie haben jetzt auf drei Wegen ein PDF erzeugt. So geht es von jedem dieser Wege aus weiter.

HTML in eine PDF-Seite rendern Das vollständige HTML-Recipe: unterstützte Elemente, das Streaming-Modell und die Sicherheitslage.

Wähle deinen Weg Entscheide zwischen Core, einem Framework, dem Server und welchem HTML-Renderer du verwendest.

Referenz der Core-Engine Jede Document-Methode, jeder Parameter und jeder Rückgabewert.

Cookbook Aufgabenorientierte Recipes für Styling, Tabellen, Paginierung und mehr.