Przegląd integracji NextPDF z Symfony

W skrócie

nextpdf/symfony to oficjalny pakiet Symfony 7 dla silnika NextPDF. Łączy silnik z kontenerem Symfony i udostępnia fabrykę dokumentów, którą można wstrzykiwać do własnych usług. Zawiera też funkcje pomocnicze do odpowiedzi w protokole Hypertext Transfer Protocol (HTTP) oraz ścieżkę asynchronicznego generowania plików w formacie Portable Document Format (PDF), dzięki czemu zadania mogą działać w tle.

Co zapewnia pakiet

Pakiet NextPDF Symfony osadza silnik nextpdf/core w aplikacji Symfony jako standardowy pakiet. Dodaje następujące elementy składowe; każdy z nich zweryfikowano z kodem źródłowym pakietu w src/Symfony/:

• Punkt wejścia pakietu — NextPDF\Symfony\NextPdfBundle rozszerza klasę bazową Bundle Symfony i rejestruje jeden compiler pass.
• Rozszerzenie wstrzykiwania zależności — NextPDF\Symfony\DependencyInjection\NextPdfExtension ładuje definicje usług, przekształca drzewo konfiguracji na parametry kontenera oraz udostępnia alias konfiguracji nextpdf.
• Typowane drzewo konfiguracji — NextPDF\Symfony\DependencyInjection\Configuration definiuje schemat konfiguracji nextpdf. Waliduje wartości typu enum, ustawia wartości domyślne oraz korzysta z symboli zastępczych parametrów %kernel.*%.
• Wstrzykiwalna fabryka dokumentów — NextPDF\Symfony\Service\PdfFactory tworzy nowe, wstępnie skonfigurowane instancje NextPDF\Core\Document. Stanowi odpowiednik statycznej fasady w Symfony.
• Funkcje pomocnicze odpowiedzi HTTP — NextPDF\Symfony\Http\PdfResponse buduje odpowiedzi inline, do pobrania oraz strumieniowane, ze stałym zestawem nagłówków bezpieczeństwa zgodnych z Open Worldwide Application Security Project (OWASP).
• Ścieżka asynchronicznego generowania — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler oraz NextPDF\Symfony\Message\PdfBuilderInterface integrują się z Symfony Messenger, dzięki czemu renderowanie plików PDF może odbywać się w procesie roboczym.
• Detektor rozszerzeń na etapie kompilacji — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass wykrywa opcjonalne rozszerzenia NextPDF i rejestruje ich usługi tylko wtedy, gdy te rozszerzenia są obecne.

Kontrakt kontenera

Pakiet rejestruje niewielki, stabilny zestaw publicznych usług kontenera. Usługa dokumentu nextpdf.document (z aliasami NextPDF\Contracts\PdfDocumentInterface oraz NextPDF\Core\Document) nie jest współdzielona: każde jej pobranie zwraca odrębny, jednorazowy dokument. Jest to zgodne z kontraktem kontenera PHP Standard Recommendation 11 (PSR-11): dwa kolejne wywołania get() z tym samym identyfikatorem mogą zwrócić różne wartości w zależności od konfiguracji kontenera — zobacz PSR-11 §1.1.2. Brak współdzielenia wiązania jest celowy. Dokument gromadzi stan właściwy dla danego renderowania, dlatego nowa instancja na każde żądanie zapobiega wyciekowi stanu między żądaniami w długo działających procesach roboczych.

Rejestr czcionek (NextPDF\Contracts\FontRegistryInterface) działa odwrotnie: jest współdzielonym singletonem. Rejestr obrazów ma znacznik kernel.reset, dzięki czemu jego ograniczona pamięć podręczna jest czyszczona między żądaniami w procesach roboczych FrankenPHP i Messenger. Pełną tabelę usług i aliasów zawiera strona konfiguracji.

Opcjonalne logowanie

Rejestry czcionek i obrazów przyjmują opcjonalny logger PHP Standard Recommendation 3 (PSR-3). Pakiet wiąże Psr\Log\LoggerInterface tylko wtedy, gdy aplikacja go dostarcza (nullOnInvalid()). Logowanie pozostaje więc opcjonalnym współpracownikiem, a nie sztywną zależnością. Jest to zgodne z kontraktem loggera PSR-3, w którym logger jest wstrzykiwanym, wymiennym współpracownikiem (PSR-3).

Funkcje edycji core a funkcje opcjonalne

Sam pakiet jest oprogramowaniem edycji core na licencji Apache-2.0. Kilka funkcji jest dostępnych dopiero po zainstalowaniu obok niego opcjonalnego pakietu:

Funkcja	Wymaga	Wykrywanie
Generowanie PDF, PdfFactory, PdfResponse	tylko core	zawsze dostępne
Generowanie asynchroniczne	symfony/messenger	handler aktywuje się, gdy Messenger jest zainstalowany
Renderowanie HTML przez Chrome DevTools Protocol (CDP)	nextpdf/artisan	sprawdzenie class_exists na etapie kompilacji
Archiwizacja PDF/A, podpisy cyfrowe	nextpdf/premium (instaluje Pro)	sprawdzenie class_exists na etapie kompilacji

Gdy nextpdf/premium jest zainstalowany, pakiet może zastosować bazową konfigurację podpisu PDF Advanced Electronic Signatures (PAdES) B-B. Wyższe profile podpisu wykraczają poza zakres dokumentacji tego pakietu. Macierz edycji znajduje się w dokumentacji NextPDF Premium.

Kiedy używać tego pakietu

Użyj nextpdf/symfony, gdy tworzysz pliki PDF w aplikacji HTTP Symfony 7 lub w procesie roboczym. Pakiet udostępnia usługi zarządzane przez kontener, rejestry bezpieczne dla procesów roboczych oraz bezpieczne odpowiedzi dla pobieranych plików, dzięki czemu nie musisz ręcznie podłączać silnika. Jeśli potrzebujesz tylko jednorazowego generowania w skrypcie, wystarczy sam pakiet edycji core nextpdf/core.

Zgodność

Każdy wiersz to normatywne stwierdzenie zawarte na tej stronie, powiązane z pełnym 64-znakowym szesnastkowym reference_id z zamkniętego korpusu organizacji opracowującej standardy (SDO). Proweniencja (manifest korpusu, transport pobierania) znajduje się w _sidecars/rag-citations.yaml.

Specyfikacja	Klauzula	reference_id	Stwierdzenie
PSR-11	psr_11_container#1.1.2.p3.b		Kontrakt wartości zwracanej przez get() kontenera
PSR-3	psr_3_logger#x3.p17		Opcjonalna zależność LoggerInterface

Kontekst komercyjny

Podpisy cyfrowe i archiwizacja PDF/A stają się dostępne, gdy obok pakietu zainstalowany jest nextpdf/premium (Pro). Te opcjonalne funkcje Pro nie wymagają żadnych zmian w kodzie pakietu Core opisanego tutaj. Zobacz </get-license/?intent=symfony-pro>.

Zobacz także

• /integrations/symfony/install/ — instalacja i rejestracja pakietu.
• /integrations/symfony/configuration/ — pełne drzewo konfiguracji nextpdf i tabela usług.
• /integrations/symfony/quickstart/ — gotowy do uruchomienia kontroler oraz przykład asynchroniczny.
• /integrations/symfony/boot-and-discovery/ — jak Symfony wykrywa i uruchamia pakiet.
• /integrations/symfony/production-usage/ — bezpieczeństwo procesów roboczych, strumieniowanie i wzorce asynchroniczne.