Uruchamianie i wykrywanie NextPDF w Symfony

W skrócie

Jądro rejestruje NextPdfBundle. Rozszerzenie DI pakietu ładuje services.php i rozstrzyga drzewo konfiguracji do postaci parametrów kontenera. Następnie pojedynczy przebieg kompilatora podłącza opcjonalne rozszerzenia oraz rozgrzewanie czcionek.

Jak Symfony Flex wykrywa pakiet

Plik composer.json pakietu deklaruje wskazówkę automatycznej rejestracji:

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

W aplikacji używającej Symfony Flex ta wskazówka dodaje NextPDF\Symfony\NextPdfBundle do config/bundles.php dla każdego środowiska (all). Bez Symfony Flex dodaj pakiet ręcznie w config/bundles.php. Model rejestracji pakietów Symfony opisuje w dokumentacji pod adresem (https://symfony.com/doc/current/bundles.html). Klasy pakietu są ładowane automatycznie zgodnie z prefiksem PHP Standard Recommendation (PSR)-4 NextPDF\Symfony\, odwzorowanym na src/Symfony/. Autoloader PSR-4 odwzorowuje ten prefiks przestrzeni nazw na wskazany katalog bazowy (PSR-4 §2).

Sekwencja rozruchu

Sekwencja rozruchu zweryfikowana na podstawie kodu źródłowego pakietu:

1. Jądro rejestruje pakiety. Kernel::registerBundles() odczytuje config/bundles.php i tworzy instancję NextPDF\Symfony\NextPdfBundle, która rozszerza Symfony\Component\HttpKernel\Bundle\Bundle.
2. Budowa pakietu. NextPdfBundle::build() wywołuje metodę nadrzędną, a następnie rejestruje pojedynczy przebieg kompilatora: OptionalExtensionPass. NextPdfBundle::getPath() zwraca katalog główny pakietu.
3. Ładowanie rozszerzenia. Rozszerzenie DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) uruchamia processConfiguration() dla Configuration. Zapisuje rozstrzygnięte wartości jako parametry kontenera nextpdf.*, a następnie ładuje config/services.php za pomocą PhpFileLoader.
4. Zabezpieczenie wymaganych rozszerzeń. NextPdfExtension::load() na końcu sprawdza obecność ext-mbstring oraz ext-zlib i natychmiast zgłasza błąd, jeśli ich brakuje.
5. Wykonanie przebiegu kompilatora. Podczas kompilacji kontenera OptionalExtensionPass::process() konfiguruje flagi dostępności rozszerzeń w PdfFactory, warunkowo rejestruje klienta podpisu oraz urzędu znakowania czasem (TSA), a także planuje rozgrzewanie i zablokowanie rejestru czcionek.
6. Skompilowanie i zbuforowanie kontenera. Symfony zapisuje skompilowany kontener. cache:warmup wykonuje ten krok, zanim ruch trafi do aplikacji.

Przebiegi kompilatora

Pakiet rejestruje dokładnie jeden przebieg, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, w NextPdfBundle::build(). Działa on w domyślnej grupie przebiegów (przed optymalizacją). Przebieg wykonuje cztery kroki. Każdy krok ma zabezpieczenia, więc pomija działanie, gdy brakuje jego danych wejściowych:

• Flagi rozszerzeń — dodaje wywołania metod setArtisanAvailable(...) oraz setProAvailable(...) do definicji PdfFactory. Wartości pochodzą z sond class_exists wykonywanych w czasie kompilacji dla fabryki przeglądarki Artisan oraz klasy Pro PDF/A.
• Rejestracja podpisującego — rejestruje fabrykę informacji o certyfikacie oraz usługę podpisującego dla podstawowego profilu B-B, gdy nextpdf.signature jest obecne, enabled ma wartość true i ustawiono certyfikat.
• Klient TSA — rejestruje usługę klienta TSA, gdy nextpdf.tsa ma adres URL (Uniform Resource Locator).
• Rozgrzewanie czcionek — dodaje wywołania metod warmup() oraz lock() do definicji rejestru czcionek, gdy nextpdf.preload_fonts nie jest puste.

Powiązania kontenera

config/services.php definiuje usługi. Usługa dokumentu nextpdf.document (aliasowana do NextPDF\Contracts\PdfDocumentInterface oraz NextPDF\Core\Document) jest niewspółdzielona: każde rozstrzygnięcie zwraca nowy dokument. PSR-11 wyraźnie dopuszcza takie zachowanie; kolejne wywołania get() dla tego samego identyfikatora mogą zwracać różne wartości (PSR-11 §1.1.2). Rejestr czcionek jest współdzielony i blokowany po rozgrzewaniu. Rejestr obrazów jest współdzielony i oznaczony etykietą kernel.reset. Pełna tabela znajduje się w /integrations/symfony/configuration/.

Kolejność rozstrzygania konfiguracji

1. Wbudowane wartości domyślne z Configuration (getConfigTreeBuilder()).
2. Nadpisania aplikacji w config/packages/nextpdf.yaml oraz nadpisania środowiskowe w config/packages/<env>/.
3. Symfony rozstrzyga symbole zastępcze parametrów %kernel.*%. Na przykład fonts_path przyjmuje domyślnie wartość %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() zapisuje scalony wynik do parametrów kontenera nextpdf.*, z których korzystają services.php oraz przebieg kompilatora.

Nieprawidłowe wartości powodują błąd w kroku 1–2 i skutkują wyjątkiem Symfony InvalidConfigurationException.

Diagnostyka

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

Pierwsze polecenie wyświetla zarejestrowane usługi. Drugie wypisuje scaloną konfigurację. Trzecie przebudowuje kontener i ponownie uruchamia sondy rozszerzeń wykonywane w czasie kompilacji.

Zgodność

Każdy wiersz odpowiada normatywnemu stwierdzeniu z tej strony, powiązanemu z pełnym 64-znakowym szesnastkowym reference_id z bramkowanego korpusu organizacji opracowujących normy (SDO). Informacje o pochodzeniu (manifest korpusu, transport pobierania) znajdują się w _sidecars/rag-citations.yaml.

Specyfikacja	Klauzula	reference_id	Stwierdzenie
PSR-11	psr_11_container#1.1.2.p3.b		Rozstrzyganie kontenera może się różnić przy każdym wywołaniu
PSR-4	psr_4_autoload#x1.x2.p5		Odwzorowanie prefiksu przestrzeni nazw na katalog bazowy

Zobacz też

• /integrations/symfony/integration/ — kompleksowy przewodnik po podłączaniu.
• /integrations/symfony/install/ — instalacja i rejestracja.
• /integrations/symfony/configuration/ — pełne drzewo konfiguracji i tabela usług.
• /integrations/symfony/overview/ — podsumowanie możliwości.