HTML in PDF umwandeln mit PHP

Was Sie brauchen

• Einen API-Key. Legen Sie ihn in der App unter API-Schlüssel an und exportieren Sie ihn als FORMFEED_API_KEY. Zum Ausprobieren ist ein Test-Key (ff_test_…) richtig. Siehe Quickstart.
• PHP. Sie brauchen PHP 8 mit den Erweiterungen curl und json, die fast jede Installation hat.
• Eine HTML-Datei. invoice.html neben dem Programm: ein vollständiges Dokument, das CSS inline oder verlinkt. Ein Beispiel steht weiter unten.

Das Programm

Das Programm liest invoice.html, sendet sie mit Papierformat und Rändern, wartet auf das Ergebnis, wenn die API mit 202 antwortet, bricht mit der Meldung der API ab, wenn etwas nicht stimmt, und speichert das PDF.

<?php
$body = [
    'html' => file_get_contents('invoice.html'),
    'settings' => [
        'paper' => ['format' => 'A4'],
        'margin' => ['top' => '20mm', 'right' => '18mm', 'bottom' => '20mm', 'left' => '18mm'],
    ],
];

// one call with the key: the decoded answer (a render or a problem document) and its status code
function api(string $url, ?array $body = null): array {
    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('FORMFEED_API_KEY'),
            'Content-Type: application/json',
        ],
    ] + ($body === null ? [] : [CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($body)]));
    $answer = curl_exec($curl);
    // a connection that never got an answer: no status code to look at
    if ($answer === false) {
        fwrite(STDERR, curl_error($curl) . PHP_EOL);
        exit(1);
    }
    return [json_decode($answer, true), curl_getinfo($curl, CURLINFO_RESPONSE_CODE)];
}

[$render, $status] = api('https://api-eu.formfeed.dev/v1/renders', $body);

// not done within 60 seconds: the answer is 202 and the render goes on in the background;
// its result answers the same way until the render has finished
while ($status === 202) {
    sleep(2);
    [$render, $status] = api('https://api-eu.formfeed.dev/v1/renders/' . $render['id'] . '/result');
}

// every error is a problem document (RFC 9457) with a title and a detail
if ($status >= 400) {
    fwrite(STDERR, $render['title'] . ': ' . ($render['detail'] ?? '') . PHP_EOL);
    exit(1);
}

file_put_contents('invoice.pdf', file_get_contents($render['download_url']));
echo $render['id'], ' ', $render['page_count'], ' page(s), ', $render['units'], ' unit(s)', PHP_EOL;

Ausführen

Es gibt die ID des Renderings, die Seitenzahl und die verbrauchten Einheiten aus, und invoice.pdf liegt neben dem Programm.

export FORMFEED_API_KEY=ff_test_...
php render.php

Was an PHP besonders ist

• Arrays werden zu JSON. json_encode macht aus dem verschachtelten Array den Request-Body; json_decode(…, true) liefert Beispieldaten und Antwort als Arrays zurück.
• Der Download. file_get_contents auf die download_url braucht allow_url_fopen. Wo das aus ist, holen Sie die URL mit einem zweiten cURL-Handle; sie ist signiert und braucht keinen Authorization-Header.
• Kein SDK nötig. Es gibt kein PHP-Paket zu installieren oder aktuell zu halten: Die API ist ein POST mit JSON-Body.

Eine HTML-Datei, die gut druckt

Das HTML wird gedruckt, wie es ist, mit den Print-Regeln, die Chromium unterstützt. Webfonts laden über ein <link>, und zwei CSS-Regeln halten eine lange Tabelle über mehrere Seiten lesbar:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
    <style>
      body { font-family: 'Inter', sans-serif; font-size: 10pt; color: #1e293b; }
      h1 { font-size: 20pt; color: #312e81; }
      table { width: 100%; border-collapse: collapse; }
      td, th { padding: 2mm; border-bottom: 1px solid #e2e8f0; text-align: left; }
      thead { display: table-header-group; } /* repeats the head row on every page */
      tr { break-inside: avoid; }
    </style>
  </head>
  <body>
    <h1>Invoice 2026-0042</h1>
    <table>
      <thead><tr><th>Item</th><th>Amount</th></tr></thead>
      <tbody><tr><td>Consulting</td><td>960.00 €</td></tr></tbody>
    </table>
  </body>
</html>

Was die Einstellungen steuern

• Papier. paper.format nimmt A4, Letter und die anderen üblichen Namen, landscape: true dreht es, und width mit height setzt ein eigenes Format, etwa ein Etikett mit 100 × 150 mm.
• Ränder. Je Seite, als CSS-Längen wie 20mm. Ein Hintergrund, der bis zum Rand reichen soll, braucht Ränder von 0.
• Kopf- und Fußzeile. header.html und footer.html wiederholen sich auf jeder Seite im oberen und unteren Rand; Elemente mit den Klassen pageNumber und totalPages zeigen die Seitenzahlen.
• Platzhalter. Mit "engine": "jinja2" (oder liquid, handlebars) und einem data-Objekt wird {{ … }} im HTML vor dem Drucken gefüllt, mit allen Helfern für Beträge, Datumsangaben, Barcodes und Diagramme.

Wann eine Vorlage das bessere Werkzeug ist

HTML zu senden ist richtig für Seiten, die Ihre Anwendung ohnehin rendert. Wenn Sie das Dokument selbst gestalten (Rechnungen, Zertifikate, Berichte), gibt Ihnen eine gespeicherte Vorlage einen Editor mit seitengenauer Vorschau, Versionen und eine Anfrage, die nur Daten enthält. Der Guide zur PDF-Rechnung dieser Sprache zeigt diese Variante.

Wenn die API nein sagt

• Eine Form für jeden Fehler. Fehler sind Problem-Dokumente (RFC 9457) mit type, title, status, detail, einem stabilen code und der request_id, die Sie dem Support nennen; die type-URL führt zu einer Seite über diesen Fehler. Die Liste steht in der Fehlerreferenz.
• Die üblichen. 401 unauthorized bei fehlendem oder widerrufenem Schlüssel, 404 template_not_found bei falschem Vorlagennamen, 422 template_runtime_error, wenn die Vorlage an den Daten scheitert, 429 rate_limited über den Anfragen pro Sekunde des Tarifs, 402 quota_exceeded, wenn die Einheiten des Free-Tarifs verbraucht sind (ein bezahlter Tarif rechnet weitere Einheiten ab, bis zu seiner Obergrenze).
• Sicher wiederholen. Senden Sie beim POST einen Idempotency-Key-Header und wiederholen Sie die Anfrage mit demselben Schlüssel, wenn Sie nicht wissen, ob der erste Versuch ankam: 24 Stunden lang liefert der Schlüssel die erste Antwort, statt erneut zu rendern und zu berechnen. Gespeichert wird die Antwort, sobald der erste Versuch beantwortet ist; wiederholen Sie also nicht, solange er noch laufen kann. Auch Probleme unter 500 werden gespeichert, eine korrigierte Anfrage braucht deshalb einen neuen Schlüssel.

Die Aufgabe um dieses Programm

Dieser Guide ist ein Programm. Was die Aufgabe darum herum braucht, von der Vorlage bis zu Limits und Preis, steht auf der Seite HTML-zu-PDF-API.

Weitere Guides für PHP

• PDF-Rechnung aus JSON erzeugen mit PHP
• ZUGFeRD-E-Rechnung erstellen mit PHP
• Open-Graph-Bilder erzeugen mit PHP
• PDFs aus einer CSV erzeugen mit PHP
• PDFs zusammenfügen und mit Passwort schützen mit PHP
• PDF asynchron rendern und den Webhook prüfen mit PHP

FAQ

Lässt sich statt eines HTML-Strings eine URL rendern?

Ja: Senden Sie url statt html. Es muss eine öffentliche https-Seite sein, die ohne Ihre Cookies oder Header geladen wird; Adressen in privaten Netzen werden abgelehnt, und eine Seite, die nicht binnen 30 Sekunden lädt, scheitert mit navigation_failed.

Wie groß darf das HTML sein?

Bis zu 5 MB je Anfrage. Bilder und Schriften werden per URL geholt und zählen nicht dazu. Die Limits je Tarif stehen in der Doku.

Läuft JavaScript in der Seite?

Ja, Chromium führt es vor dem Drucken aus; so entstehen Diagramme. Es wartet, bis das Netzwerk ruht, höchstens 30 Sekunden; eine Seite, die nicht fertig lädt, scheitert also mit render_timeout, statt zu hängen.

HTML zu PDF in anderen Sprachen

• Node.js (TypeScript)
• Python
• Go
• C# (.NET)
• Java
• Ruby
• curl