Rozwiązywanie problemów z pakietem NextPDF dla Symfony

W skrócie

Większość problemów dotyczy jednego z czterech obszarów: wykrywania, walidacji konfiguracji, połączeń w kontenerze albo routingu Messengera. Każda sekcja zestawia objaw z odpowiadającym mu zachowaniem pakietu, a następnie podaje polecenie konsoli, którym można potwierdzić naprawę.

Pakiet nie jest zarejestrowany

Objaw: nie udaje się automatycznie wstrzyknąć PdfFactory albo debug:container nextpdf nic nie zwraca.

Przyczyna: pakiet nie został dodany do config/bundles.php. Flex mógł się nie uruchomić albo aplikacja nie korzysta z Flexa.

Rozwiązanie:

php bin/console debug:container nextpdf

Jeśli polecenie nie zwraca żadnych usług, dodaj pakiet ręcznie:

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

Plik composer.json pakietu zawiera wskazówkę dotyczącą automatycznej rejestracji w sekcji extra.symfony.bundles. Dotyczy ona wyłącznie aplikacji z włączonym Flexem.

Uruchamianie kończy się niepowodzeniem z powodu brakującego rozszerzenia PHP

Objaw: podczas uruchamiania jądro zgłasza wyjątek RuntimeException, w którym pojawia się ext-mbstring lub ext-zlib.

Przyczyna: wynika to z NextPdfExtension::guardRequiredExtensions() — celowego zabezpieczenia pakietu, które szybko zgłasza błąd. Nie jest to wada.

Rozwiązanie: włącz wskazane rozszerzenie w pliku php.ini, a następnie zrestartuj środowisko uruchomieniowe. Potwierdź włączenie poleceniem:

php -m | grep -E 'mbstring|zlib'

Konfiguracja jest odrzucana na etapie budowania

Objaw: Symfony zgłasza wyjątek Symfony\Component\Config\Definition\Exception\InvalidConfigurationException podczas cache:clear lub cache:warmup.

Przyczyna: wartość nie mieści się w schemacie. Plik Configuration.php definiuje następujące ograniczenia:

• page_format musi być jedną z wartości: A4, A3, A5, Letter, Legal, Tabloid.
• orientation musi mieć wartość P lub L.
• unit musi być jedną z wartości: pt, mm, cm, in.
• pdfa musi mieć wartość null, 4, 4e lub 4f.
• image_cache_mb musi mieć wartość >= 0.

Rozwiązanie: wyświetl scaloną konfigurację, a następnie popraw klucz, który spowodował błąd:

php bin/console debug:config nextpdf

PDF/A lub podpisywanie nie przynoszą efektu

Objaw: sekcja pdfa lub signature jest ustawiona, ale wynikiem pozostaje zwykły plik w formacie Portable Document Format (PDF).

Przyczyna: te funkcje wymagają nextpdf/premium. Podczas kompilacji PdfFactory stosuje PDF/A wyłącznie wtedy, gdy wykryje rozszerzenie Pro. Przebieg kompilatora rejestruje moduł podpisujący tylko wtedy, gdy signature.enabled ma wartość true oraz ustawiono signature.certificate.

Rozwiązanie: potwierdź, że Premium jest zainstalowany i że istnieje usługa modułu podpisującego:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Jeśli Premium nie jest obecny, pakiet przechowuje konfigurację, ale celowo pozostawia ją nieaktywną. Funkcja podpisywania z Pro udokumentowana w pakiecie obsługuje podstawowy profil B-B. Dokumentacja NextPDF Premium opisuje profile wykraczające poza B-B.

Renderowanie przez Chrome nie działa

Objaw: konfiguracja artisan jest ignorowana.

Przyczyna: renderowanie za pomocą Chrome DevTools Protocol (CDP) wymaga nextpdf/artisan. Podczas kompilacji przebieg kompilatora sprawdza jego obecność za pomocą class_exists. Jeśli rozszerzenie jest nieobecne, mechanizm renderujący nie zostaje podłączony.

Rozwiązanie:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

Sprawdzenie odbywa się podczas kompilacji kontenera. Po zainstalowaniu rozszerzenia ponownie uruchom cache:clear.

Procedura obsługi Messengera nigdy nie zostaje wywołana

Objaw: po wysłaniu GeneratePdfMessage żaden plik PDF nie zostaje zapisany.

Przyczyny i rozwiązania:

• Wiadomość nie jest routowana — dodaj w pliku config/packages/messenger.yaml wpis routingu mapujący NextPDF\Symfony\Message\GeneratePdfMessage na transport, a następnie uruchom proces roboczy (php bin/console messenger:consume <transport>).
• Konstruktor nie jest w lokalizatorze — procedura obsługi pobiera konstruktor z lokalizatora PHP Standards Recommendation 11 (PSR-11) na podstawie jego identyfikatora będącego nazwą klasy. Identyfikator kontenera to łańcuch znaków, który jednoznacznie identyfikuje wpis (PSR-11 §1.1.2). Jeśli lokalizator nie ma zarejestrowanej klasy konstruktora, procedura obsługi zgłasza wyjątek RuntimeException z informacją, że skonfigurowany konstruktor musi implementować PdfBuilderInterface. Zarejestruj konstruktor, a następnie odwołaj się do niego z lokalizatora.

Sprawdź routing oraz lokalizator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Wiadomość jest odrzucana podczas wysyłania z wyjątkiem InvalidArgumentException

Objaw: utworzenie GeneratePdfMessage zgłasza wyjątek InvalidArgumentException.

Przyczyna: obiekt transferu danych (DTO) wiadomości waliduje dane wejściowe. Stosowane reguły odrzucania są następujące:

• pusta ścieżka wyjściowa albo ścieżka zawierająca bajt zerowy;
• schemat wrappera strumienia (na przykład php://...);
• segment przechodzenia do katalogu nadrzędnego .. (separatory POSIX lub Windows);
• ścieżka wyjściowa, która nie kończy się na .pdf (bez rozróżniania wielkości liter);
• wartość builderClass, która nie jest składniowo poprawną nazwą klasy.

Rozwiązanie: przekaż bezwzględną ścieżkę systemu plików zakończoną na .pdf oraz rzeczywistą, w pełni kwalifikowaną nazwę klasy konstruktora.

Dokument zawiera nieaktualne dane

Objaw: wygenerowany plik PDF zawiera treść z poprzedniego żądania.

Przyczyna: długo działający proces roboczy przechowywał instancję Document pomiędzy żądaniami. Usługa dokumentu jest niewspółdzielona właśnie po to, by temu zapobiec.

Rozwiązanie: wywołuj PdfFactory::create() w metodzie działającej w zakresie żądania. Nigdy nie przechowuj zwróconego dokumentu w usłudze współdzielonej.

Wykaz poleceń diagnostycznych

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Zgodność

Każdy wiersz zawiera normatywne stwierdzenie z tej strony, powiązane z pełnym 64-znakowym szesnastkowym reference_id z korpusu organizacji opracowującej standardy (SDO) dostępnego za bramką. Informacje o pochodzeniu danych, w tym manifest korpusu oraz transport pobierania, znajdują się w pliku _sidecars/rag-citations.yaml.

Specyfikacja	Klauzula	reference_id	Stwierdzenie
PSR-11	psr_11_container#1.1.2.p4		Kontrakt identyfikatora has()/get() kontenera

Zobacz także

• /integrations/symfony/install/ — instalacja i rejestracja.
• /integrations/symfony/configuration/ — pełny schemat i ograniczenia.
• /integrations/symfony/boot-and-discovery/ — wykrywanie i sekwencja uruchamiania.
• /integrations/symfony/security-and-operations/ — nagłówki bezpieczeństwa i walidacja ścieżek.