NextPDF-Symfony-Bundle konfigurieren

Auf einen Blick

Das gesamte Verhalten des Bundles wird unter dem Wurzelschlüssel nextpdf in config/packages/nextpdf.yaml konfiguriert. Für jeden Schlüssel gibt es einen Standardwert; die Konfiguration ist daher optional. Diese Seite bildet Configuration.php exakt ab.

Konfigurationsbaum

Das Schema wird von NextPDF\Symfony\DependencyInjection\Configuration definiert. Ungültige Werte führen beim Erstellen des Containers zu einer InvalidConfigurationException von Symfony.

Schlüssel der obersten Ebene

Schlüssel	Typ	Standard	Validierung
page_format	enum	A4	eines von A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	eines von P, L
unit	enum	mm	eines von pt, mm, cm, in
pdfa	scalar	null	eines von null, 4, 4e, 4f
fonts_path	scalar	%kernel.project_dir%/resources/fonts	—
cache_path	scalar	%kernel.cache_dir%/nextpdf	—
image_cache_mb	integer	50	Minimum 0
font_cache_locking	boolean	true	—
preload_fonts	Liste von Strings	[]	—

icc_profile

Schlüssel	Typ	Standard
icc_profile.rgb	scalar	null
icc_profile.cmyk	scalar	null

defaults

Wird auf jedes Dokument angewendet, das von PdfFactory erzeugt wird.

Schlüssel	Typ	Standard
defaults.creator	scalar	NextPDF
defaults.author	scalar	(leer)
defaults.language	scalar	en
defaults.margin_top	float	10.0
defaults.margin_right	float	10.0
defaults.margin_bottom	float	10.0
defaults.margin_left	float	10.0
defaults.font_family	scalar	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	variabel	null
defaults.bleed_box	variabel	null

PdfFactory liest creator, author und language aus diesem Abschnitt und wendet sie auf jedes neu erzeugte Dokument an. Die übrigen Schlüssel werden als Container-Parameter für die Nutzung durch die Engine gespeichert.

artisan

Wird nur wirksam, wenn nextpdf/artisan installiert ist und erkannt wurde.

Schlüssel	Typ	Standard
artisan.chrome_binary	scalar	null
artisan.render_timeout	integer	30
artisan.default_css	scalar	(leer)
artisan.no_sandbox	boolean	false
artisan.max_html_size	integer	5000000

signature

Wird nur wirksam, wenn nextpdf/premium installiert ist. In Kombination mit dem Bundle und der Pro-Stufe ist das unterstützte Signatur-Profil das Baseline-B-B-Profil. Der Knoten level akzeptiert die unten aufgeführten String-Werte, um die Schema-Kompatibilität mit der übrigen NextPDF-Konfigurationsfamilie zu wahren. Dieses Bundle liefert die Signatur-Fähigkeit B-B. Profile jenseits von B-B werden separat in der NextPDF Premium-Dokumentation beschrieben und hier nicht beansprucht.

Schlüssel	Typ	Standard	Validierung
signature.enabled	boolean	false	—
signature.certificate	scalar	null	—
signature.private_key	scalar	null	—
signature.password	scalar	(leer)	—
signature.extra_certs	Liste von Strings	[]	—
signature.level	enum	B-B	zulässige Werte: B-B, B-T, B-LT, B-LTA (B-B wird ausgeliefert; B-T/B-LT/B-LTA sind Schema-Kompatibilitätswerte, keine ausgelieferte Pro-Fähigkeit)

Der Compiler-Pass registriert einen Signer-Dienst nur, wenn signature.enabled wahr ist und signature.certificate gesetzt ist; andernfalls ist der Abschnitt inaktiv.

tsa

Konfiguration für den Time-Stamp-Authority-Client, den die Pro-Signatur verwendet, sofern er konfiguriert ist.

Schlüssel	Typ	Standard
tsa.url	scalar	null
tsa.username	scalar	(leer)
tsa.password	scalar	(leer)
tsa.cert	scalar	null
tsa.key	scalar	null
tsa.timeout	integer	30
tsa.allow_insecure_http	boolean	false
tsa.pinned_public_keys	Liste von Strings	[]
tsa.warn_on_key_rotation	boolean	true

Ein TSA-Client-Dienst wird nur registriert, wenn tsa.url gesetzt ist.

ocsp_cache

Schlüssel	Typ	Standard
ocsp_cache.enabled	boolean	true
ocsp_cache.ttl	integer	86400
ocsp_cache.directory	scalar	null

messenger

Schalter für die asynchrone Generierung, die verwendet werden, wenn symfony/messenger installiert ist.

Schlüssel	Typ	Standard
messenger.transport	scalar	async
messenger.timeout	integer	120
messenger.retries	integer	3

Referenzkonfiguration

Eine Konfigurationsdatei, die jeden Abschnitt mit seinen Standardwerten zeigt:

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

Container-Dienste und Aliase

Das Bundle lädt seine Dienstdefinitionen aus config/services.php. Die folgende Tabelle bildet diese Datei exakt ab.

Dienst-ID	Geteilt	Öffentlich	Hinweise
NextPDF\Typography\FontRegistry	ja	—	konstruiert aus nextpdf.fonts_path; optionaler PSR-3-Logger
NextPDF\Contracts\FontRegistryInterface	(Alias)	ja	Alias von FontRegistry
NextPDF\Graphics\ImageRegistry	ja	—	begrenztes LRU; getaggt mit kernel.reset (reset)
NextPDF\Core\DocumentFactory	ja	—	teilt sich die beiden Registries
NextPDF\Contracts\DocumentFactoryInterface	(Alias)	ja	Alias von DocumentFactory
NextPDF\Symfony\Service\PdfFactory	ja	ja	liest die defaults-, pdfa- und artisan-Parameter
NextPDF\Contracts\PdfDocumentInterface	nein	ja	Factory [PdfFactory, create]
NextPDF\Core\Document	(Alias)	—	Alias von PdfDocumentInterface
nextpdf.document	(Alias)	ja	Alias von PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	ja	zustandsloser Helfer

Das Bundle registriert zusätzlich EInvoice-Vertragsbindungen (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) nur, wenn die entsprechenden Premium-Implementierungsklassen vorhanden sind. Jede Bindung wird non-shared registriert, sodass Aufrufer jeweils eine frische Instanz erhalten. Parser-Zustand pro Aufruf gelangt niemals über Request-Grenzen hinweg.

Shared versus non-shared

nextpdf.document (und seine Aliase) ist non-shared: jede Container-Auflösung liefert ein eigenes Dokument. Unter PSR-11 darf ein Container bei aufeinanderfolgenden get()-Aufrufen mit derselben Kennung einen anderen Wert zurückgeben — PSR-11 §1.1.2. Die Font-Registry ist shared und nach dem Warmup gesperrt. Strukturelle Font-Daten werden daher einmal pro Prozess geparst und können während eines Requests nicht verändert werden.

Die Dienste FontRegistry und ImageRegistry akzeptieren einen optionalen Psr\Log\LoggerInterface, der per nullOnInvalid() gebunden wird. Der Logger ist ein austauschbarer, optionaler Kollaborator im Einklang mit dem PSR-3-Logger-Vertrag (PSR-3).

Autowiring

PdfFactory, PdfResponse, das Document-Factory-Interface und das Font-Registry-Interface sind öffentlich. Sie lassen sich aus dem Container abrufen oder in autowired Controllern und Diensten per Type-Hint angeben. Constructor-Injection von NextPDF\Symfony\Service\PdfFactory ist der empfohlene Einstiegspunkt.

Sonderfälle und Stolperfallen

• pdfa ohne Pro gesetzt — der Wert wird gespeichert, aber ignoriert. PdfFactory wendet PDF/A nur an, wenn die Pro-Erweiterung zur Compile-Zeit erkannt wird.
• image_cache_mb: 0 — gültig; deaktiviert den Bild-LRU-Cache. Negative Werte werden beim Erstellen des Containers abgelehnt.
• signature.enabled: true ohne signature.certificate — der Signer-Dienst wird nicht registriert; die Konfiguration bleibt per Design still inaktiv.
• %kernel.*%-Platzhalter — die Standards von fonts_path und cache_path nutzen Symfony-Container-Parameter; überschreiben Sie sie nur mit absoluten Pfaden, wenn der literale Pfad erforderlich ist.

Konformität

Jede Zeile auf dieser Seite ist eine normative Aussage, die an eine vollständige reference_id mit 64 Hexzeichen aus dem freigegebenen SDO-Korpus gebunden ist. Die Provenance-Angaben (Korpus-Manifest, Retrieval-Transport) stehen in _sidecars/rag-citations.yaml.

Spec	Klausel	reference_id	Aussage
PSR-11	psr_11_container#1.1.2.p3.b		get() darf pro Auflösung unterschiedliche Werte zurückgeben
PSR-3	psr_3_logger#x3.p17		Optionaler LoggerInterface-Kollaborator

Kommerzieller Kontext

Die Abschnitte signature und tsa werden nur wirksam, wenn nextpdf/premium (Pro) installiert ist. Dies ist eine optionale Pro-Fähigkeit; das hier dokumentierte Core-Bundle braucht keine Codeänderung, um sie zu übernehmen. Siehe </get-license/?intent=symfony-pro>.

Siehe auch

• /integrations/symfony/install/ — das Bundle installieren und registrieren.
• /integrations/symfony/overview/ — Übersicht der Fähigkeiten.
• /integrations/symfony/production-usage/ — Worker-Sicherheit und asynchrone Muster.
• /integrations/symfony/boot-and-discovery/ — wie die Konfiguration beim Boot aufgelöst wird.