Instalacja pakietu NextPDF dla Symfony

W skrócie

Zainstaluj pakiet za pomocą Composera. Jeśli aplikacja korzysta z Symfony Flex, pakiet zostanie zarejestrowany automatycznie. Bez Flexa zarejestruj go jednorazowo w pliku config/bundles.php.

Wymagania

W pliku composer.json pakiet definiuje następujące ograniczenia.

Zależność	Ograniczenie
php	>=8.4 <9.0
nextpdf/core	^3.0 || ^5.2
symfony/framework-bundle	^7.2
symfony/dependency-injection	^7.2
symfony/config	^7.2
symfony/http-foundation	^7.2
psr/log	^3.0

Podczas budowania kontenera pakiet sprawdza także dwa rozszerzenia PHP: ext-mbstring oraz ext-zlib. W każdym obsługiwanym środowisku uruchomieniowym PHP oba są włączone. Jeśli brakuje któregokolwiek z rozszerzeń, mechanizm zabezpieczający natychmiast przerywa działanie i zwraca czytelny komunikat.

Pakiety opcjonalne

W sekcji suggest pliku composer.json pakiet deklaruje następujące pakiety. Dodaj je, gdy potrzebujesz funkcji, które zapewniają:

Pakiet	Dodaje
nextpdf/artisan	Renderowanie HTML przez Chrome CDP, z automatycznym wykrywaniem na etapie kompilacji
nextpdf/premium	Archiwizacja PDF/A i podpis cyfrowy (instaluje wersję Pro), z automatycznym wykrywaniem na etapie kompilacji
symfony/messenger	Asynchroniczne generowanie PDF za pomocą procedury obsługi Messenger

Instalacja za pomocą Composera

composer require nextpdf/symfony

Pakiet jest ładowany automatycznie zgodnie z PHP Standard Recommendation 4 (PSR-4), pod prefiksem NextPDF\Symfony\ odwzorowanym na src/Symfony/. Deklaracja tego odwzorowania znajduje się w composer.jsonautoload.psr-4. Wygenerowany przez Composera autoloader odwzorowuje prefiks przestrzeni nazw na ten katalog bazowy, zgodnie z definicją PSR-4 §2.

Rejestracja pakietu

Symfony Flex (zalecane)

Pakiet dostarcza wpis automatycznej rejestracji w pliku composer.json:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

W aplikacji z włączonym Flexem ten wpis dodaje pakiet do config/bundles.php dla każdego środowiska (all). Nie musisz edytować tego pliku ręcznie. Model rejestracji opisuje oficjalna dokumentacja pakietów Symfony (https://symfony.com/doc/current/bundles.html).

Ręczna rejestracja (bez Flexa)

Jeśli aplikacja nie korzysta z Symfony Flex, dodaj pakiet do config/bundles.php samodzielnie:

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

Klasa pakietu to NextPDF\Symfony\NextPdfBundle. Rozszerza ona bazową klasę Symfony Symfony\Component\HttpKernel\Bundle\Bundle. Metoda getPath() pakietu zwraca katalog główny pakietu, a metoda build() rejestruje przebieg kompilatora OptionalExtensionPass.

Utworzenie pliku konfiguracyjnego

Alias konfiguracji pakietu to nextpdf. Utwórz plik config/packages/nextpdf.yaml. Po opublikowaniu recepty Flex domyślna kopia zostanie automatycznie umieszczona tutaj. Minimalny plik, który w całości opiera się na wbudowanych wartościach domyślnych, wygląda tak:

nextpdf: ~

Każdy klucz ma wartość domyślną, więc pusta konfiguracja jest poprawna. Pełne drzewo konfiguracji opisuje strona /integrations/symfony/configuration/.

Weryfikacja instalacji

Sprawdź, czy kontener widzi usługi pakietu:

php bin/console debug:container nextpdf

Wynik powinien zawierać wpisy usług, w tym alias nextpdf.document oraz NextPDF\Symfony\Service\PdfFactory. Aby sprawdzić rozwiązaną konfigurację, uruchom:

php bin/console debug:config nextpdf

To polecenie wypisuje scalone drzewo konfiguracji: własne nadpisania wraz z wartościami domyślnymi.

Przypadki brzegowe i pułapki

• Zakres ograniczeń rdzenia — pakiet akceptuje nextpdf/core^3.0 || ^5.2. Composer wybiera wersję, która spełnia wymagania pozostałej części grafu zależności. Przypnij jedną wersję główną w pliku composer.json aplikacji, jeśli potrzebujesz deterministycznej wersji silnika.
• Zabezpieczenie przed brakiem rozszerzenia — jeśli php bin/console nie uruchamia się podczas startu i wyświetla komunikat o ext-mbstring lub ext-zlib, włącz wskazane rozszerzenie w php.ini. To zamierzone zachowanie fail-fast, a nie usterka pakietu.
• Flex nie zarejestrował pakietu — wyczyść pamięć podręczną Composera i zainstaluj ponownie. Jeśli nie korzystasz z Flexa, wykonaj ręcznie krok z config/bundles.php.

Zgodność

Każdy wiersz zawiera normatywne twierdzenie z tej strony, powiązane z pełnym 64-znakowym szesnastkowym reference_id z kontrolowanego korpusu SDO. Informacje o pochodzeniu znajdują się w _sidecars/rag-citations.yaml. Obejmują one manifest korpusu oraz transport pobierania.

Specyfikacja	Klauzula	reference_id	Twierdzenie
PSR-4	psr_4_autoload#x1.x2.p5		Odwzorowanie prefiksu przestrzeni nazw autoloadera na katalog

Zobacz także

• /integrations/symfony/overview/ — co oferuje pakiet.
• /integrations/symfony/configuration/ — pełne drzewo konfiguracji i tabela usług.
• /integrations/symfony/quickstart/ — pierwszy działający kontroler.
• /integrations/symfony/boot-and-discovery/ — szczegółowe omówienie wykrywania i sekwencji uruchamiania.