Symfony-API-referentie

In het kort

Het Symfony-pakket biedt bundelregistratie, een configuratieboom, een injecteerbare fabriek voor nieuwe documenten, Hypertext Transfer Protocol (HTTP)-response-helpers en Messenger-typen voor asynchrone generatie. De meeste applicatiecode gebruikt maar twee symbolen: de PdfFactory-service die u injecteert om een Document te bouwen, en de PdfResponse-helper die dat document omzet in een veilige HTTP-response. De overige symbolen (bundel, extensie, compiler pass, configuratieboom, Messenger-data transfer object (DTO) en handler) vormen bedrading die u eenmalig configureert of die het framework voor u beheert.

Begin hier: Injecteer NextPDF\Symfony\Service\PdfFactory, roep create() aan om een nieuw Document te krijgen, en retourneer het met NextPDF\Symfony\Http\PdfResponse::download(). Het eerste voorbeeld toont die flow.

Veelvoorkomende taken

Gebruik deze drie uitvoerbare codefragmenten voor de meest voorkomende taken. Elk fragment gebruikt alleen de geverifieerde symbolen die in de tabellen hieronder worden beschreven.

Retourneer een Portable Document Format (PDF)-download vanuit een controller: injecteer de fabriek, bouw een document en geef het door aan de response-helper:

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

Wat het doet: PdfFactory::create() retourneert een nieuw, vooraf geconfigureerd Document. PdfResponse::download() verzendt het met Content-Type: application/pdf, een attachmentdispositie en de vaste beveiligingsheaders van de bundel.

Stream een grote PDF om het piekgeheugen laag te houden: gebruik de gestreamde helper en retourneer een StreamedResponse:

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

Wat het doet: PdfResponse::streamDownload() verzendt de gematerialiseerde PDF in delen en laat Content-Length weg. Gebruik streamInline() voor het inline-equivalent.

Verzend een PDF voor asynchrone generatie: stuur een GeneratePdfMessage naar een Messenger-transport zodat de rendering op een worker draait:

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

Wat het doet: de DTO draagt een builder-class-string en een gevalideerd uitvoerpad. De handler haalt de builder op, bouwt het document en slaat het op de worker op. De builder-klasse implementeert PdfBuilderInterface en wordt geregistreerd in een service locator (zie de Symfony-quickstart voor de locator- en worker-bedrading).

Fabriek

Gebruik deze tabel voor de exacte constructor en het create()-contract van de injecteerbare service die nieuwe documenten produceert.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: kernfabriek; defaults: maker, auteur, taal, marges; pdfa: optioneel PDF/A-profiel; artisanConfig: optionele Chrome-rendererconfiguratie.	Standaardwaarden worden alleen toegepast wanneer ze geconfigureerd zijn.	PdfFactory	Fouten bij containerbedrading.	De service kan een singleton zijn omdat create() een nieuw document retourneert.
PdfFactory::create()	geen.	Past maker en taal toe; past auteur alleen toe wanneer deze niet leeg is; past PDF/A en Artisan-configuratie alleen toe wanneer die beschikbaar zijn.	NextPDF\Core\Document	Fouten in de kernconfiguratie.	Gebruik eenmaal per request, command of message.
PdfFactory::setArtisanAvailable(bool $available)	available: beschikbaarheidsvlag op compile-time.	Uitgeschakeld totdat de compiler pass deze inschakelt.	void	Geen verwacht.	Interne hook die door de optionele extensie-compiler pass wordt aangeroepen.
PdfFactory::setProAvailable(bool $available)	available: beschikbaarheidsvlag op compile-time.	Uitgeschakeld totdat de compiler pass deze inschakelt.	void	Geen verwacht.	Interne hook voor Premium-beschikbaarheid.

Bundel, extensie en configuratie

Gebruik de eerste tabel voor de bedradingslaag: bundelregistratie, de nextpdf-configuratieboom en detectie van optionele extensies. De tweede tabel bevat de configuratiesleutels.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
NextPdfBundle::build(ContainerBuilder $container)	Symfony-containerbuilder.	Roept de build-methode van de parent aan en registreert OptionalExtensionPass.	void	Fouten bij registratie van de compiler pass.	Schakelt optionele detectie van Artisan- en Premium-functies in.
NextPdfBundle::getPath()	geen.	Retourneert het rootpad van het pakket.	string	Geen verwacht.	Wordt gebruikt door Symfony-bundeldetectie en bij het laden van resources.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	User-configuratiearrays en containerbuilder.	Verwerkt de nextpdf-configuratie, slaat de opgeloste parameters op, laadt servicedefinities en controleert vereiste extensies.	void	Fouten bij configuratievalidatie, het laden van services of een ontbrekende extensie.	De vereiste extensies zijn mbstring en zlib.
NextPdfExtension::getAlias()	geen.	Gebruikt nextpdf als root-configuratiesleutel.	string	Geen verwacht.	Configureer de bundel onder nextpdf:.
Configuration::getConfigTreeBuilder()	geen.	Definieert de gevalideerde nextpdf-configuratieboom.	TreeBuilder	Symfony-fouten bij configuratiedefinitie.	Spiegelt de vorm van de Laravel-configuratie waar dat praktisch is.
OptionalExtensionPass::process(ContainerBuilder $container)	Symfony-containerbuilder.	Detecteert optionele Artisan- en Premium-services en schakelt de beschikbaarheidsvlaggen van de fabriek om.	void	Fouten bij bedrading van de compiler pass.	Draait tijdens containercompilatie.

Configuratiesleutel	Type	Standaardgedrag	Opmerkingen
page_format	enum	A4; toegestane waarden zijn onder meer A3, A5, Letter, Legal en Tabloid.	Geldt voor het standaard aanmaken van documenten.
orientation	enum	P; toegestane waarden zijn P en L.	Gebruik expliciete documentaanroepen wanneer een pagina een andere stand nodig heeft.
unit	enum	mm; toegestane waarden zijn pt, mm, cm en in.	Houdt de framework-standaardwaarden in lijn met de kerneenheden.
pdfa	`string	null`	null; toegestane waarden zijn 4, 4e en 4f.
fonts_path / cache_path	string	Projectpad voor lettertypen en kernel-cachepad.	Zorg dat elk pad leesbaar of beschrijfbaar is voor zijn rol tijdens runtime.
signature.*	array	Standaard uitgeschakeld met handtekeningniveau B-B.	Biedt certificaat, sleutel, wachtwoord, extra certificaten en niveau.
tsa.*	array	Uitgeschakeld wanneer de Uniform Resource Locator (URL) null is; de timeout is standaard 30 seconden.	Ondersteunt inloggegevens, bestanden voor mutual Transport Layer Security (mTLS), public-key-pins en HTTP-beleid.
ocsp_cache.*	array	Ingeschakeld met een time to live (TTL) van 86400 seconden.	Wordt gebruikt door validatie- en langetermijn-handtekeningflows wanneer beschikbaar.
messenger.*	array	Transport async, timeout 120, retries 3.	Gebruikt door workflows voor asynchrone generatie.
artisan.*	array	De Chrome-renderer is uitgeschakeld tenzij deze geconfigureerd en geïnstalleerd is.	Mapt naar ChromeRendererConfig wanneer de optionele renderer beschikbaar is.
defaults.*	array	Maker NextPDF, auteur leeg, taal en, standaardmarges en -lettertype.	Toegepast door PdfFactory::create().

HTTP-responses

Gebruik deze tabel om een response-helper te kiezen op basis van weergavemodus en buffering: inline-weergave of download, gebufferd of gestreamd. De tabel toont ook het gedrag voor bestandsnaam en headers.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: gebouwd document; filename: bestandsnaam van de response.	Voegt .pdf toe wanneer dit ontbreekt.	Symfony\Component\HttpFoundation\Response	Fouten bij kernserialisatie.	Stelt het PDF-contenttype en defensieve headers in.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Hetzelfde als inline; de dispositie is attachment.	Browser-downloadresponse.	Response	Hetzelfde als inline.	Gebruik voor expliciete downloads.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Hetzelfde als inline.	Verzendt de gematerialiseerde PDF-bytes in delen.	StreamedResponse	Hetzelfde als inline.	Dit voorkomt niet dat het document wordt gematerialiseerd.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Hetzelfde als streamInline; de dispositie is attachment.	Download-streamresponse.	StreamedResponse	Hetzelfde als streamInline.	Pas vóór rendering een beleid voor de uitvoergrootte toe.

Messenger

Gebruik deze tabel voor het asynchrone pad: de message-DTO die u verzendt, de builder-interface die u implementeert en de handler die op de worker draait.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string die PdfBuilderInterface implementeert; outputPath: doel-.pdf; builderContext: serialiseerbare data.	Lege context-array.	Message-DTO.	InvalidArgumentException bij een ongeldige fully qualified class name (FQCN), stream wrapper, null byte, traversal, leeg pad of een doel dat niet .pdf is.	Messenger-transporten dragen data, geen closures.
PdfBuilderInterface::build(Document $document, array $context): Document	document: nieuw geconfigureerd document; context: serialiseerbare message-data.	Geen standaardcontext buiten de message-waarde.	Geconfigureerd Document.	Builder-specifieke excepties.	Maak builders deterministisch en idempotent.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	PDF-fabriek en de getagde builder-service locator.	Tijdens constructie wordt geen document aangemaakt.	GeneratePdfHandler	Fouten bij containerbedrading.	De locator mag alleen implementaties van PdfBuilderInterface blootstellen.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: gevalideerde message-DTO.	Haalt de builder uit de container, bouwt het document en slaat het op.	void	Ontbrekende builder-service, ongeldig builder-resultaat, fouten bij het wegschrijven in de kern.	Geef de voorkeur aan service-builders boven statische callbacks.

Ontwikkelnotities

• Sla een Document niet op als service. Sla PdfFactory op en roep create() aan voor elke werkeenheid.
• Plaats alleen serialiseerbare context in de wachtrij. Plaats geen open streams, closures of request-objecten in builderContext.
• Gebruik een striktere uitvoerpad-policy dan de DTO wanneer de deployment tenant-specifieke opslagroots heeft.