Symfony-API-Referenz

Auf einen Blick

Das Symfony-Paket stellt die Bundle-Registrierung, einen Konfigurationsbaum, eine injizierbare Factory für neue Dokumente, HTTP-Response-Helfer sowie Messenger-Typen für die asynchrone Generierung bereit. In nahezu jedem Anwendungscode kommen nur zwei Symbole zum Einsatz: der PdfFactory-Service, den Sie injizieren, um ein Document zu erstellen, und der PdfResponse-Helfer, der dieses Dokument in eine sichere HTTP-Response umwandelt. Die übrigen Symbole (Bundle, Extension, Compiler-Pass, Konfigurationsbaum, Messenger-DTO und Handler) gehören zur Verdrahtung, die Sie einmal konfigurieren oder die das Framework für Sie verwaltet.

Hier beginnen: Wenn Sie neu einsteigen, injizieren Sie NextPDF\Symfony\Service\PdfFactory, rufen create() auf, um ein neues Document zu erhalten, und geben es mit NextPDF\Symfony\Http\PdfResponse::download() zurück. Das erste Beispiel unten zeigt diesen Ablauf.

Häufige Aufgaben

Drei lauffähige Snippets für die häufigsten Aufgaben. Sie nutzen ausschließlich die verifizierten Symbole, die in den folgenden Tabellen dokumentiert sind.

Einen PDF-Download aus einem Controller zurückgeben: Injizieren Sie die Factory, erstellen Sie ein Dokument und übergeben Sie es dem Response-Helfer:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Was passiert: PdfFactory::create() liefert ein neues, vorkonfiguriertes Document. PdfResponse::download() sendet es mit Content-Type: application/pdf, einer Attachment-Disposition und den festen Sicherheits-Headern des Bundles.

Ein großes PDF streamen, um den maximalen Speicherverbrauch niedrig zu halten: Verwenden Sie den anderen Helfer und geben Sie eine StreamedResponse zurück:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Was passiert: PdfResponse::streamDownload() gibt das materialisierte PDF in Chunks aus und lässt Content-Length weg; verwenden Sie streamInline() für die Inline-Variante.

Ein PDF zur asynchronen Generierung anstoßen: Senden Sie eine GeneratePdfMessage an einen Messenger-Transport, damit das Rendering auf einem Worker läuft:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Was passiert: Das DTO enthält einen Builder-Class-String und einen validierten Ausgabepfad. Der Handler löst den Builder auf, erstellt das Dokument und speichert es auf dem Worker. Die Builder-Klasse implementiert PdfBuilderInterface und ist in einem Service-Locator registriert (siehe Symfony-Quickstart zur Locator- und Worker-Verdrahtung).

Factory

Nutzen Sie diese Tabelle, wenn Sie den genauen Konstruktor und den create()-Vertrag des injizierbaren Services benötigen, der neue Dokumente erzeugt.

Symbol	Parameter	Standardverhalten	Liefert	Wirft oder schlägt fehl mit	Hinweise
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: Core-Factory; defaults: Creator, Autor, Sprache, Ränder; pdfa: optionales PDF/A-Profil; artisanConfig: optionale Chrome-Renderer-Konfiguration.	Defaults werden nur angewendet, wenn sie konfiguriert sind.	PdfFactory	Container-Verdrahtungsfehler.	Der Service kann als Singleton verwendet werden, weil create() jeweils ein neues Dokument liefert.
PdfFactory::create()	keine.	Wendet Creator und Sprache an; wendet den Autor nur an, wenn er nicht leer ist; wendet PDF/A und Artisan-Konfiguration nur an, wenn verfügbar.	NextPDF\Core\Document	Core-Konfigurationsfehler.	Einmal pro Request, Command oder Message verwenden.
PdfFactory::setArtisanAvailable(bool $available)	available: Verfügbarkeits-Flag zur Compile-Zeit.	Deaktiviert, bis der Compiler-Pass es aktiviert.	void	keine erwartet.	Interner Hook, den der optionale Extension-Compiler-Pass aufruft.
PdfFactory::setProAvailable(bool $available)	available: Verfügbarkeits-Flag zur Compile-Zeit.	Deaktiviert, bis der Compiler-Pass es aktiviert.	void	keine erwartet.	Interner Hook für die Premium-Verfügbarkeit.

Bundle, Extension und Konfiguration

Diese Tabelle beschreibt die Verdrahtungsebene: Ziehen Sie sie heran, wenn Sie das Bundle registrieren, den nextpdf-Konfigurationsbaum auflösen oder die Erkennung optionaler Extensions nachvollziehen möchten. Die zweite Tabelle listet die Konfigurationsschlüssel selbst auf.

Symbol	Parameter	Standardverhalten	Liefert	Wirft oder schlägt fehl mit	Hinweise
NextPdfBundle::build(ContainerBuilder $container)	Symfony-Container-Builder.	Ruft die Build-Methode der Elternklasse auf und registriert OptionalExtensionPass.	void	Fehler bei der Registrierung des Compiler-Passes.	Aktiviert die optionale Erkennung von Artisan- und Premium-Features.
NextPdfBundle::getPath()	keine.	Liefert den Root-Pfad des Pakets.	string	keine erwartet.	Wird von der Symfony-Bundle-Erkennung und dem Ressourcen-Laden verwendet.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Benutzer-Konfigurations-Arrays und Container-Builder.	Verarbeitet die nextpdf-Konfiguration, speichert die aufgelösten Parameter, lädt die Service-Definitionen und prüft anschließend die erforderlichen Extensions.	void	Fehler bei der Konfigurationsvalidierung, beim Laden der Services oder durch fehlende Extensions.	Erforderliche Extensions sind mbstring und zlib.
NextPdfExtension::getAlias()	keine.	Nutzt nextpdf als Root-Konfigurationsschlüssel.	string	keine erwartet.	Konfigurieren Sie das Bundle unter nextpdf:.
Configuration::getConfigTreeBuilder()	keine.	Definiert den validierten nextpdf-Konfigurationsbaum.	TreeBuilder	Symfony-Konfigurationsdefinitionsfehler.	Spiegelt die Laravel-Konfigurationsform wider, soweit praktikabel.
OptionalExtensionPass::process(ContainerBuilder $container)	Symfony-Container-Builder.	Erkennt optionale Artisan- und Premium-Services und setzt die Verfügbarkeits-Flags der Factory.	void	Fehler bei der Compiler-Pass-Verdrahtung.	Läuft während der Container-Kompilierung.

Konfigurationsschlüssel	Typ	Standardverhalten	Hinweise
page_format	enum	A4; zulässige Werte sind unter anderem A3, A5, Letter, Legal und Tabloid.	Gilt für die Standarderstellung von Dokumenten.
orientation	enum	P; zulässige Werte sind P und L.	Verwenden Sie explizite Dokumentaufrufe, wenn eine Seite eine andere Ausrichtung benötigt.
unit	enum	mm; zulässige Werte sind pt, mm, cm und in.	Hält die Framework-Defaults mit den Core-Einheiten konsistent.
pdfa	`string	null`	null; zulässige Werte sind 4, 4e und 4f.
fonts_path / cache_path	string	Projekt-Schriftartenpfad und Kernel-Cache-Pfad.	Halten Sie beide Pfade je nach Laufzeitrolle lesbar oder beschreibbar.
signature.*	array	Standardmäßig deaktiviert mit Signatur-Level B-B.	Stellt Zertifikat, Schlüssel, Passwort, zusätzliche Zertifikate und Level bereit.
tsa.*	array	Deaktiviert, wenn die URL null ist; das Timeout liegt standardmäßig bei 30 Sekunden.	Unterstützt Anmeldedaten, mTLS-Dateien, Public-Key-Pins und HTTP-Policy.
ocsp_cache.*	array	Aktiviert mit einer TTL von 86400 Sekunden.	Wird von Validierungs- und Langzeitsignaturabläufen genutzt, wenn verfügbar.
messenger.*	array	Transport async, Timeout 120, Retries 3.	Wird von Workflows zur asynchronen Generierung genutzt.
artisan.*	array	Chrome-Renderer deaktiviert, sofern nicht konfiguriert und installiert.	Wird auf ChromeRendererConfig gemappt, wenn der optionale Renderer verfügbar ist.
defaults.*	array	Creator NextPDF, Autor leer, Sprache en, Standardränder und Standardschriftart.	Angewendet durch PdfFactory::create().

HTTP-Responses

Nutzen Sie diese Tabelle, um den passenden Response-Helfer zu wählen: Inline-Anzeige oder Download, gepuffert oder gestreamt, einschließlich des Dateinamen- und Header-Verhaltens der einzelnen Helfer.

Symbol	Parameter	Standardverhalten	Liefert	Wirft oder schlägt fehl mit	Hinweise
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: gebautes Dokument; filename: Dateiname der Response.	Fügt .pdf hinzu, falls es fehlt.	Symfony\Component\HttpFoundation\Response	Core-Serialisierungsfehler.	Setzt den PDF-Content-Type und defensive Header.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Wie inline; die Disposition ist attachment.	Response für Browser-Downloads.	Response	Wie inline.	Für explizite Downloads verwenden.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Wie inline.	Gibt die materialisierten PDF-Bytes in Chunks aus.	StreamedResponse	Wie inline.	Umgeht die Materialisierung des Dokuments nicht.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Wie streamInline; die Disposition ist attachment.	Response für Download-Streams.	StreamedResponse	Wie streamInline.	Wenden Sie die Ausgabegrößen-Policy vor dem Rendern an.

Messenger

Nutzen Sie diese Tabelle, wenn Sie den asynchronen Pfad aufbauen: das Message-DTO, das Sie versenden, das Builder-Interface, das Sie implementieren, und den Handler, der auf dem Worker läuft.

Symbol	Parameter	Standardverhalten	Liefert	Wirft oder schlägt fehl mit	Hinweise
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: Class-String, der PdfBuilderInterface implementiert; outputPath: Ziel-.pdf; builderContext: serialisierbare Daten.	Leeres Kontext-Array.	Message-DTO.	InvalidArgumentException bei ungültigem FQCN, Stream-Wrapper, Null-Byte, Traversal, leerem Pfad oder einem Ziel ohne .pdf.	Messenger-Transporte übertragen Daten, keine Closures.
PdfBuilderInterface::build(Document $document, array $context): Document	document: frisches konfiguriertes Dokument; context: serialisierbare Message-Daten.	Kein zusätzlicher Standardkontext über den Message-Wert hinaus.	Konfiguriertes Document.	Builder-spezifische Exceptions.	Halten Sie Builder deterministisch und idempotent.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	PDF-Factory und getaggter Builder-Service-Locator.	Während der Konstruktion wird kein Dokument erstellt.	GeneratePdfHandler	Container-Verdrahtungsfehler.	Der Locator sollte nur PdfBuilderInterface-Implementierungen bereitstellen.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: validiertes Message-DTO.	Löst den Builder aus dem Container auf, erstellt das Dokument und speichert es.	void	Fehlender Builder-Service, ungültiges Builder-Ergebnis, Core-Schreibfehler.	Bevorzugen Sie Service-Builder gegenüber statischen Callbacks.

Entwicklungshinweise

• Registrieren Sie ein Document nicht als Service. Registrieren Sie PdfFactory und rufen Sie create() für jede Arbeitseinheit auf.
• Stellen Sie nur serialisierbaren Kontext in die Queue. Legen Sie keine offenen Streams, Closures oder Request-Objekte in builderContext.
• Halten Sie die Ausgabepfad-Policy strenger als das DTO, wenn das Deployment mandantenspezifische Storage-Roots hat.