Dokumentacja API Symfony

W skrócie

Pakiet dla Symfony udostępnia rejestrację bundle’a, drzewo konfiguracji, wstrzykiwaną fabrykę dokumentów, pomocniki odpowiedzi Hypertext Transfer Protocol (HTTP) oraz typy Messengera do generowania asynchronicznego. W większości kodu aplikacji używane są tylko dwa symbole: usługa PdfFactory, którą wstrzykujesz, aby zbudować obiekt Document, oraz pomocnik PdfResponse, który zamienia ten dokument w bezpieczną odpowiedź HTTP. Pozostałe symbole (bundle, rozszerzenie, przebieg kompilatora, drzewo konfiguracji, obiekt transferu danych (DTO) Messengera oraz moduł obsługi) to elementy okablowania, które konfigurujesz raz albo pozostawiasz frameworkowi.

Zacznij tutaj: wstrzyknij NextPDF\Symfony\Service\PdfFactory, wywołaj create(), aby uzyskać nowy obiekt Document, i zwróć go za pomocą NextPDF\Symfony\Http\PdfResponse::download(). Pierwszy przykład pokazuje cały przepływ.

Typowe zadania

Skorzystaj z tych trzech gotowych do uruchomienia fragmentów kodu przy najczęstszych zadaniach. Każdy fragment korzysta wyłącznie ze zweryfikowanych symboli opisanych w poniższych tabelach.

Zwróć z kontrolera plik do pobrania w formacie Portable Document Format (PDF): wstrzyknij fabrykę, zbuduj dokument i przekaż go do pomocnika odpowiedzi:

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

Co robi: PdfFactory::create() zwraca nowy, wstępnie skonfigurowany obiekt Document. PdfResponse::download() wysyła go z nagłówkiem Content-Type: application/pdf, dyspozycją załącznika oraz stałymi nagłówkami zabezpieczeń bundle’a.

Przesyłaj duży plik PDF strumieniowo, aby ograniczyć szczytowe zużycie pamięci: użyj pomocnika strumieniowego i zwróć 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');
    }
}

Co robi: PdfResponse::streamDownload() emituje zmaterializowany plik PDF we fragmentach i pomija Content-Length; użyj streamInline() jako odpowiednika wyświetlanego w przeglądarce.

Aby wygenerować plik PDF asynchronicznie, wyślij GeneratePdfMessage do transportu Messengera, aby renderowanie odbyło się w procesie roboczym:

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

Co robi: DTO przenosi class-string konstruktora oraz zwalidowaną ścieżkę wyjściową. Moduł obsługi rozwiązuje konstruktor, buduje dokument i zapisuje go w procesie roboczym. Klasa konstruktora implementuje PdfBuilderInterface i jest zarejestrowana w lokalizatorze usług (przewodnik szybkiego startu dla Symfony opisuje okablowanie lokalizatora i procesu roboczego).

Fabryka

Ta tabela opisuje dokładny konstruktor oraz kontrakt create() wstrzykiwanej usługi tworzącej nowe dokumenty.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: fabryka rdzenia; defaults: twórca, autor, język, marginesy; pdfa: opcjonalny profil PDF/A; artisanConfig: opcjonalna konfiguracja renderera Chrome.	Wartości domyślne są stosowane tylko wtedy, gdy zostały skonfigurowane.	PdfFactory	Błędy okablowania kontenera.	Usługa może być singletonem, ponieważ create() zwraca nowy dokument.
PdfFactory::create()	brak.	Ustawia twórcę i język; ustawia autora tylko wtedy, gdy nie jest pusty; stosuje konfigurację PDF/A i Artisan tylko wtedy, gdy jest dostępna.	NextPDF\Core\Document	Błędy konfiguracji rdzenia.	Wywołuj raz na żądanie, polecenie lub komunikat.
PdfFactory::setArtisanAvailable(bool $available)	available: flaga dostępności w czasie kompilacji.	Wyłączone, dopóki nie włączy go przebieg kompilatora.	void	brak oczekiwanych.	Wewnętrzny hook wywoływany przez opcjonalny przebieg kompilatora rozszerzenia.
PdfFactory::setProAvailable(bool $available)	available: flaga dostępności w czasie kompilacji.	Wyłączone, dopóki nie włączy go przebieg kompilatora.	void	brak oczekiwanych.	Wewnętrzny hook dostępności funkcji Premium.

Bundle, rozszerzenie i konfiguracja

Pierwsza tabela opisuje warstwę okablowania: rejestrację bundle’a, drzewo konfiguracji nextpdf oraz wykrywanie opcjonalnych rozszerzeń. Druga tabela zawiera listę kluczy konfiguracji.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
NextPdfBundle::build(ContainerBuilder $container)	Konstruktor kontenera Symfony.	Wywołuje nadrzędną metodę build i rejestruje OptionalExtensionPass.	void	Błędy rejestracji przebiegu kompilatora.	Włącza wykrywanie opcjonalnych funkcji Artisan i Premium.
NextPdfBundle::getPath()	brak.	Zwraca główną ścieżkę pakietu.	string	brak oczekiwanych.	Używane przez wykrywanie bundle’i i ładowanie zasobów w Symfony.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Tablice konfiguracji użytkownika i konstruktor kontenera.	Przetwarza konfigurację nextpdf, przechowuje rozwiązane parametry, ładuje definicje usług i weryfikuje wymagane rozszerzenia.	void	Błędy walidacji konfiguracji, ładowania usług lub braku wymaganego rozszerzenia.	Wymaganymi rozszerzeniami są mbstring i zlib.
NextPdfExtension::getAlias()	brak.	Używa nextpdf jako głównego klucza konfiguracji.	string	brak oczekiwanych.	Skonfiguruj bundle pod kluczem nextpdf:.
Configuration::getConfigTreeBuilder()	brak.	Definiuje walidowane drzewo konfiguracji nextpdf.	TreeBuilder	Błędy definicji konfiguracji w Symfony.	Odzwierciedla strukturę konfiguracji Laravel tam, gdzie jest to praktyczne.
OptionalExtensionPass::process(ContainerBuilder $container)	Konstruktor kontenera Symfony.	Wykrywa opcjonalne usługi Artisan i Premium oraz przełącza flagi dostępności fabryki.	void	Błędy okablowania przebiegu kompilatora.	Uruchamia się podczas kompilacji kontenera.

Klucz konfiguracji	Typ	Zachowanie domyślne	Uwagi
page_format	enum	A4; dozwolone wartości obejmują A3, A5, Letter, Legal i Tabloid.	Dotyczy domyślnego tworzenia dokumentu.
orientation	enum	P; dozwolone wartości to P i L.	Używaj jawnych wywołań dokumentu, gdy strona wymaga innej orientacji.
unit	enum	mm; dozwolone wartości to pt, mm, cm i in.	Utrzymuje domyślne wartości frameworka w zgodzie z jednostkami rdzenia.
pdfa	`string	null`	null; dozwolone wartości to 4, 4e i 4f.
fonts_path / cache_path	string	Ścieżka czcionek projektu i ścieżka pamięci podręcznej kernela.	Zadbaj, aby każda ścieżka była odpowiednio odczytywalna albo zapisywalna w czasie wykonywania.
signature.*	array	Domyślnie wyłączone, z poziomem podpisu B-B.	Udostępnia certyfikat, klucz, hasło, dodatkowe certyfikaty oraz poziom.
tsa.*	array	Wyłączone, gdy adres Uniform Resource Locator (URL) ma wartość null; limit czasu domyślnie wynosi 30 sekund.	Obsługuje poświadczenia, pliki wzajemnego uwierzytelniania Transport Layer Security (mTLS), przypięcia kluczy publicznych oraz politykę HTTP.
ocsp_cache.*	array	Włączone z czasem życia (TTL) wynoszącym 86400 sekund.	Używane przez przepływy walidacji i długoterminowych podpisów, gdy jest dostępne.
messenger.*	array	Transport async, limit czasu 120, ponowne próby 3.	Używane przez przepływy generowania asynchronicznego.
artisan.*	array	Renderer Chrome jest wyłączony, chyba że został skonfigurowany i zainstalowany.	Mapuje się na ChromerendererConfig, gdy opcjonalny renderer jest dostępny.
defaults.*	array	Twórca NextPDF, autor pusty, język en, domyślne marginesy i czcionka.	Stosowane przez PdfFactory::create().

Odpowiedzi HTTP

Ta tabela pomaga wybrać pomocnika odpowiedzi według trybu wyświetlania i buforowania: wyświetlanie w przeglądarce lub pobieranie, buforowane albo strumieniowe. Pokazuje również zachowanie nazwy pliku i nagłówków.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: zbudowany dokument; filename: nazwa pliku odpowiedzi.	Dodaje .pdf, gdy go brakuje.	Symfony\Component\HttpFoundation\Response	Błędy serializacji rdzenia.	Ustawia typ zawartości PDF oraz nagłówki ochronne.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Tak samo jak inline; dyspozycja to załącznik.	Odpowiedź wymuszająca pobieranie w przeglądarce.	Response	Tak samo jak inline.	Używaj do jawnych pobrań.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Tak samo jak inline.	Emituje bajty zmaterializowanego pliku PDF we fragmentach.	StreamedResponse	Tak samo jak inline.	Nie eliminuje materializacji dokumentu.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Tak samo jak streamInline; dyspozycja to załącznik.	Odpowiedź strumieniowa z pobieraniem.	StreamedResponse	Tak samo jak streamInline.	Zastosuj politykę rozmiaru wyjścia przed renderowaniem.

Messenger

Ta tabela opisuje ścieżkę asynchroniczną: DTO wysyłanego komunikatu, interfejs konstruktora, który implementujesz, oraz moduł obsługi działający w procesie roboczym.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string implementujący PdfBuilderInterface; outputPath: docelowy .pdf; builderContext: serializowalne dane.	Pusta tablica kontekstu.	DTO komunikatu.	InvalidArgumentException dla nieprawidłowej w pełni kwalifikowanej nazwy klasy (FQCN), stream wrappera, bajtu null, przejścia po katalogach, pustej ścieżki lub celu innego niż .pdf.	Transporty Messengera przenoszą dane, a nie domknięcia.
PdfBuilderInterface::build(Document $document, array $context): Document	document: nowy, skonfigurowany dokument; context: serializowalne dane komunikatu.	Brak domyślnego kontekstu poza wartością komunikatu.	Skonfigurowany Document.	Wyjątki specyficzne dla konstruktora.	Zadbaj, aby konstruktory były deterministyczne i idempotentne.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	Fabryka PDF oraz otagowany lokalizator usług konstruktorów.	Podczas konstrukcji nie jest tworzony żaden dokument.	GeneratePdfHandler	Błędy okablowania kontenera.	Lokalizator powinien udostępniać wyłącznie implementacje PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: zwalidowane DTO komunikatu.	Rozwiązuje konstruktor z kontenera, buduje dokument i zapisuje go.	void	Brakująca usługa konstruktora, nieprawidłowy wynik konstruktora, błędy zapisu rdzenia.	Preferuj konstruktory usługowe zamiast statycznych wywołań zwrotnych.

Uwagi dla programistów

• Nie przechowuj obiektu Document jako usługi. Przechowuj PdfFactory i wywołuj create() dla każdej jednostki pracy.
• Kolejkuj wyłącznie serializowalny kontekst. Nie umieszczaj otwartych strumieni, domknięć ani obiektów żądania w builderContext.
• Stosuj politykę ścieżki wyjściowej bardziej restrykcyjną niż DTO, jeśli wdrożenie ma katalogi główne pamięci masowej właściwe dla najemcy.