Konfiguracja pakietu NextPDF Symfony

W skrócie

Całe zachowanie pakietu konfigurujesz pod kluczem głównym nextpdf w pliku config/packages/nextpdf.yaml. Każdy klucz ma wartość domyślną, więc ustawiasz tylko wartości, które chcesz zmienić. Ta strona dokładnie odzwierciedla Configuration.php.

Drzewo konfiguracji

NextPDF\Symfony\DependencyInjection\Configuration definiuje schemat. Nieprawidłowe wartości powodują podczas budowania kontenera błąd zgłaszany jako wyjątek Symfony InvalidConfigurationException.

Klucze najwyższego poziomu

Klucz	Typ	Domyślnie	Walidacja
`page_format`	enum	`A4`	jedna z wartości `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	enum	`P`	jedna z wartości `P`, `L`
`unit`	enum	`mm`	jedna z wartości `pt`, `mm`, `cm`, `in`
`pdfa`	skalar	`null`	jedna z wartości `null`, `4`, `4e`, `4f`
`fonts_path`	skalar	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	skalar	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	liczba całkowita	`50`	minimum `0`
`font_cache_locking`	wartość logiczna	`true`	—
`preload_fonts`	lista łańcuchów znaków	`[]`	—

`icc_profile`

Klucz	Typ	Domyślnie
`icc_profile.rgb`	skalar	`null`
`icc_profile.cmyk`	skalar	`null`

`defaults`

Dotyczy każdego dokumentu tworzonego przez PdfFactory.

Klucz	Typ	Domyślnie
`defaults.creator`	skalar	`NextPDF`
`defaults.author`	skalar	(puste)
`defaults.language`	skalar	`en`
`defaults.margin_top`	liczba zmiennoprzecinkowa	`10.0`
`defaults.margin_right`	liczba zmiennoprzecinkowa	`10.0`
`defaults.margin_bottom`	liczba zmiennoprzecinkowa	`10.0`
`defaults.margin_left`	liczba zmiennoprzecinkowa	`10.0`
`defaults.font_family`	skalar	`dejavusans`
`defaults.font_size`	liczba zmiennoprzecinkowa	`12.0`
`defaults.trim_box`	zmienna	`null`
`defaults.bleed_box`	zmienna	`null`

PdfFactory odczytuje creator, author oraz language z tej sekcji i stosuje je do każdego nowego dokumentu. Pakiet przechowuje pozostałe klucze jako parametry kontenera używane przez silnik.

`artisan`

Ma zastosowanie tylko wtedy, gdy nextpdf/artisan jest zainstalowany i wykryty.

Klucz	Typ	Domyślnie
`artisan.chrome_binary`	skalar	`null`
`artisan.render_timeout`	liczba całkowita	`30`
`artisan.default_css`	skalar	(puste)
`artisan.no_sandbox`	wartość logiczna	`false`
`artisan.max_html_size`	liczba całkowita	`5000000`

`signature`

Ma zastosowanie tylko wtedy, gdy nextpdf/premium jest zainstalowany. Gdy pakiet i poziom Pro są obecne, obsługiwaną konfiguracją podpisywania jest profil bazowy B-B. Węzeł level przyjmuje poniższe wartości tekstowe, aby zachować zgodność schematu z szerszą rodziną konfiguracji NextPDF. Ten pakiet udostępnia podpisywanie B-B. Profile wykraczające poza B-B są opisane oddzielnie w dokumentacji NextPDF Premium i nie są tutaj deklarowane.

Klucz	Typ	Domyślnie	Walidacja
`signature.enabled`	wartość logiczna	`false`	—
`signature.certificate`	skalar	`null`	—
`signature.private_key`	skalar	`null`	—
`signature.password`	skalar	(puste)	—
`signature.extra_certs`	lista łańcuchów znaków	`[]`	—
`signature.level`	enum	`B-B`	akceptowany zbiór: `B-B`, `B-T`, `B-LT`, `B-LTA` (B-B jest dostarczane; `B-T`/`B-LT`/`B-LTA` to wartości zgodności schematu, a nie dostarczona funkcja Pro)

Compiler pass rejestruje usługę podpisującą tylko wtedy, gdy signature.enabled ma wartość true oraz signature.certificate jest ustawiony; w przeciwnym razie sekcja pozostaje nieaktywna.

`tsa`

Konfiguracja klienta urzędu znacznika czasu (Time Stamp Authority, TSA), używana przez podpisywanie w Pro, gdy jest skonfigurowana.

Klucz	Typ	Domyślnie
`tsa.url`	skalar	`null`
`tsa.username`	skalar	(puste)
`tsa.password`	skalar	(puste)
`tsa.cert`	skalar	`null`
`tsa.key`	skalar	`null`
`tsa.timeout`	liczba całkowita	`30`
`tsa.allow_insecure_http`	wartość logiczna	`false`
`tsa.pinned_public_keys`	lista łańcuchów znaków	`[]`
`tsa.warn_on_key_rotation`	wartość logiczna	`true`

Pakiet rejestruje usługę klienta TSA tylko wtedy, gdy tsa.url jest ustawiony.

`ocsp_cache`

Klucz	Typ	Domyślnie
`ocsp_cache.enabled`	wartość logiczna	`true`
`ocsp_cache.ttl`	liczba całkowita	`86400`
`ocsp_cache.directory`	skalar	`null`

`messenger`

Ustawienia generowania asynchronicznego, używane wtedy, gdy symfony/messenger jest zainstalowany.

Klucz	Typ	Domyślnie
`messenger.transport`	skalar	`async`
`messenger.timeout`	liczba całkowita	`120`
`messenger.retries`	liczba całkowita	`3`

Przykładowa konfiguracja

Plik konfiguracyjny pokazujący każdą sekcję wraz z jej wartościami domyślnymi:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Usługi i aliasy kontenera

Pakiet ładuje swoje definicje usług z pliku config/services.php. Poniższa tabela dokładnie odzwierciedla zawartość tego pliku.

Identyfikator usługi	Współdzielona	Publiczna	Uwagi
`NextPDF\Typography\FontRegistry`	tak	—	tworzony z `nextpdf.fonts_path`; opcjonalny rejestrator zgodny z PHP Standard Recommendation 3 (PSR-3)
`NextPDF\Contracts\FontRegistryInterface`	(alias)	tak	alias dla `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	tak	—	pamięć podręczna o ograniczonym rozmiarze typu least-recently-used (LRU); oznaczona tagiem `kernel.reset` (`reset`)
`NextPDF\Core\DocumentFactory`	tak	—	współdzieli oba rejestry
`NextPDF\Contracts\DocumentFactoryInterface`	(alias)	tak	alias dla `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	tak	tak	odczytuje parametry `defaults`, `pdfa` oraz `artisan`
`NextPDF\Contracts\PdfDocumentInterface`	nie	tak	fabryka `[PdfFactory, create]`
`NextPDF\Core\Document`	(alias)	—	alias dla `PdfDocumentInterface`
`nextpdf.document`	(alias)	tak	alias dla `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	tak	bezstanowy pomocnik

Pakiet rejestruje również wiązania kontraktów EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) tylko wtedy, gdy istnieją odpowiednie klasy implementacji Premium. Każda usługa jest niewspółdzielona, więc kod wywołujący otrzymuje nową instancję. Stan parsera z pojedynczego wywołania nigdy nie wycieka pomiędzy żądaniami.

Współdzielone a niewspółdzielone

nextpdf.document (oraz jego aliasy) jest niewspółdzielony: każde pobranie z kontenera zwraca odrębny dokument. Zgodnie z PHP Standard Recommendation 11 (PSR-11) kontener może zwrócić inną wartość przy kolejnych wywołaniach get() z tym samym identyfikatorem; zobacz PSR-11 §1.1.2. Rejestr czcionek jest współdzielony i blokowany po rozgrzaniu. Strukturalne dane czcionek są parsowane raz na proces i nie mogą zostać zmienione w trakcie żądania.

Usługi FontRegistry oraz ImageRegistry przyjmują opcjonalny Psr\Log\LoggerInterface; Symfony wiąże go za pomocą nullOnInvalid(). Rejestrator pozostaje opcjonalną, wymienną zależnością zgodną z kontraktem rejestratora PSR-3.

Autowiring

PdfFactory, PdfResponse, interfejs fabryki dokumentów oraz interfejs rejestru czcionek są publiczne. Można je pobrać z kontenera albo wskazać jako typ w autowirowanych kontrolerach i usługach. Zalecanym punktem wejścia jest wstrzykiwanie przez konstruktor NextPDF\Symfony\Service\PdfFactory.

Przypadki brzegowe i pułapki

pdfa ustawione bez Pro — wartość jest przechowywana, ale ignorowana. PdfFactory stosuje format Portable Document Format/Archival (PDF/A) tylko wtedy, gdy rozszerzenie Pro zostanie wykryte podczas kompilacji.
image_cache_mb: 0 — prawidłowe; wyłącza pamięć podręczną LRU obrazów. Wartości ujemne są odrzucane podczas budowania kontenera.
signature.enabled: true bez signature.certificate — usługa podpisująca nie jest rejestrowana; konfiguracja celowo pozostaje nieaktywna bez zgłaszania błędu.
Symbole zastępcze %kernel.*% — wartości domyślne fonts_path oraz cache_path używają parametrów kontenera Symfony; nadpisuj ścieżkami bezwzględnymi tylko wtedy, gdy wymagana jest dosłowna ścieżka.

Zgodność

Każdy wiersz zawiera normatywne twierdzenie z tej strony, powiązane z pełnym 64-znakowym szesnastkowym reference_id z bramkowanego korpusu organizacji opracowującej standardy (standards development organization, SDO). Pochodzenie, w tym manifest korpusu i transport użyty do pobrania, znajduje się w pliku _sidecars/rag-citations.yaml.

Specyfikacja	Klauzula	reference_id	Twierdzenie
PSR-11	`psr_11_container#1.1.2.p3.b`		get() może zwracać różne wartości przy każdym pobraniu
PSR-3	`psr_3_logger#x3.p17`		Opcjonalna zależność LoggerInterface

Kontekst komercyjny

Sekcje signature i tsa mają zastosowanie tylko wtedy, gdy nextpdf/premium (Pro) jest zainstalowany. Ta opcjonalna funkcja Pro nie wymaga żadnych zmian w kodzie pakietu Core opisanego w tym dokumencie. Zobacz </get-license/?intent=symfony-pro>.

Zobacz też

/integrations/symfony/install/ — zainstaluj i zarejestruj pakiet.
/integrations/symfony/overview/ — przejrzyj podsumowanie możliwości.
/integrations/symfony/production-usage/ — bezpieczeństwo procesów roboczych i wzorce asynchroniczne.
/integrations/symfony/boot-and-discovery/ — zobacz, jak konfiguracja jest ustalana podczas uruchamiania.