Integracja NextPDF z Symfony

W skrócie

Zainstaluj nextpdf/symfony, pozwól Flex zarejestrować bundle albo zarejestruj go samodzielnie, dodaj config/packages/nextpdf.yaml i wstrzyknij PdfFactory. Traktuj tę stronę jako indeks kroków integracji. Każdy krok odsyła do bardziej szczegółowego przewodnika.

Instalacja

composer require nextpdf/symfony

Bundle wymaga nextpdf/core^3.0 || ^5.2, symfony/*^7.2 oraz psr/log^3.0. Klasy są automatycznie ładowane pod prefiksem PHP Standards Recommendation (PSR)-4 NextPDF\Symfony\, odwzorowanym na src/Symfony/. Autoloader PSR-4 odwzorowuje ten prefiks przestrzeni nazw na katalog bazowy (PSR-4 §2). Pełną listę wymagań i pakietów opcjonalnych znajdziesz na stronie /integrations/symfony/install/.

Uruchamianie i automatyczne wykrywanie

Gdy używasz Symfony Flex, wpis extra.symfony.bundles w pliku composer.json bundle rejestruje NextPDF\Symfony\NextPdfBundle dla wszystkich środowisk. Bez Flex dodaj go samodzielnie do config/bundles.php:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

Pełną sekwencję uruchamiania oraz działanie przebiegów kompilatora opisuje strona /integrations/symfony/boot-and-discovery/.

Powiązania kontenera

Plik config/services.php w bundle rejestruje następujące usługi:

Usługa / alias	Cykl życia
`NextPDF\Symfony\Service\PdfFactory`	współdzielona, publiczna; wstrzykuj ją
`nextpdf.document` → `PdfDocumentInterface` → `Document`	niewspółdzielona, publiczna; nowa przy każdym rozwiązywaniu
`NextPDF\Contracts\FontRegistryInterface`	współdzielona, zablokowana po rozgrzaniu
`NextPDF\Graphics\ImageRegistry`	współdzielona, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	współdzielona
`NextPDF\Symfony\Http\PdfResponse`	publiczny, bezstanowy pomocnik

Powiązanie dokumentu celowo jest niewspółdzielone. PSR-11 zezwala kontenerowi na zwracanie różnych wartości w kolejnych wywołaniach get() dla jednego identyfikatora. Nowy dokument pozwala uniknąć współdzielonego stanu między żądaniami w długo działających procesach roboczych (PSR-11 §1.1.2). Pełną tabelę usług i aliasów, w tym warunkowe powiązania EInvoice, znajdziesz na stronie /integrations/symfony/configuration/.

Publikowanie konfiguracji

Aliasem konfiguracji jest nextpdf. Utwórz config/packages/nextpdf.yaml. Gdy Flex publikuje recepturę, dodaje domyślną kopię automatycznie. Każdy klucz ma wartość domyślną, więc minimalny plik wygląda tak:

nextpdf: ~

Pełne drzewo konfiguracji jest udokumentowane na stronie /integrations/symfony/configuration/.

Pierwsze użycie

Wstrzyknij PdfFactory, a następnie zwróć dokument przez PdfResponse:

<?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 PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

Kompletny kontroler oraz asynchroniczną ścieżkę Messenger znajdziesz na stronie /integrations/symfony/quickstart/.

Test dymny pakietu bundle

Zweryfikuj integrację bez pisania kodu aplikacji:

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf powinno wyświetlić PdfFactory, alias nextpdf.document oraz rejestry. lint:container sprawdza, czy każdy argument usługi można rozwiązać. Aby przetestować generowanie, dodaj powyższy kontroler, a następnie wyślij żądanie do /hello.pdf.

Publiczne punkty wejścia API

Publiczna powierzchnia interfejsu programowania aplikacji (API) udostępnia kodowi aplikacji następujące symbole:

Symbol	Przeznaczenie
`NextPDF\Symfony\Service\PdfFactory::create()`	nowy, wstępnie skonfigurowany `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	buforowana odpowiedź z nagłówkami zabezpieczeń
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	strumieniowa odpowiedź przesyłana fragmentami
`NextPDF\Symfony\Message\GeneratePdfMessage`	obiekt transferu danych (DTO) do generowania asynchronicznego (walidowany)
`NextPDF\Symfony\Message\PdfBuilderInterface`	kontrakt buildera rozwiązywany przez handler

Zgodność

Każdy wiersz wymienia twierdzenie normatywne sformułowane na tej stronie. Każde twierdzenie jest przypięte do pełnego, 64-znakowego szesnastkowego reference_id z reglamentowanego korpusu organizacji opracowującej standardy (SDO). Pochodzenie (manifest korpusu i transport pobierania) znajduje się w _sidecars/rag-citations.yaml.

Specyfikacja	Punkt	reference_id	Twierdzenie
PSR-11	`psr_11_container#1.1.2.p4`		Kontrakt identyfikatora has()/get() kontenera
PSR-4	`psr_4_autoload#x1.x2.p5`		Odwzorowanie przestrzeni nazw przez autoloader

Zobacz także

/integrations/symfony/install/ — wymagania i rejestracja.
/integrations/symfony/boot-and-discovery/ — wykrywanie, uruchamianie i przebieg kompilatora.
/integrations/symfony/configuration/ — pełny schemat i tabela usług.
/integrations/symfony/quickstart/ — gotowy do uruchomienia kontroler i przykład asynchroniczny.
/integrations/symfony/production-usage/ — bezpieczeństwo procesów roboczych i strumieniowanie.