การกำหนดค่า NextPDF Symfony bundle

ภาพรวมโดยสรุป

กำหนดพฤติกรรมทั้งหมดของ bundle ได้ภายใต้คีย์ราก nextpdf ใน config/packages/nextpdf.yaml ทุกคีย์มีค่าเริ่มต้น จึงต้องตั้งค่าเฉพาะรายการที่ต้องการเปลี่ยนแปลงเท่านั้น หน้านี้สะท้อน Configuration.php ทุกประการ

ผังโครงสร้างการกำหนดค่า

NextPDF\Symfony\DependencyInjection\Configuration กำหนดสคีมา ค่าที่ไม่ถูกต้องจะทำให้การ build container ล้มเหลวพร้อม Symfony InvalidConfigurationException

คีย์ระดับบนสุด

คีย์	ชนิด	ค่าเริ่มต้น	การตรวจสอบความถูกต้อง
`page_format`	enum	`A4`	หนึ่งในค่า `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	enum	`P`	หนึ่งในค่า `P`, `L`
`unit`	enum	`mm`	หนึ่งในค่า `pt`, `mm`, `cm`, `in`
`pdfa`	scalar	`null`	หนึ่งในค่า `null`, `4`, `4e`, `4f`
`fonts_path`	scalar	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	scalar	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	integer	`50`	ค่าต่ำสุด `0`
`font_cache_locking`	boolean	`true`	—
`preload_fonts`	รายการของ string	`[]`	—

`icc_profile`

คีย์	ชนิด	ค่าเริ่มต้น
`icc_profile.rgb`	scalar	`null`
`icc_profile.cmyk`	scalar	`null`

`defaults`

มีผลกับเอกสารทุกฉบับที่ PdfFactory สร้างขึ้น

คีย์	ชนิด	ค่าเริ่มต้น
`defaults.creator`	scalar	`NextPDF`
`defaults.author`	scalar	(ว่าง)
`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`	variable	`null`
`defaults.bleed_box`	variable	`null`

PdfFactory อ่านค่า creator, author และ language จากส่วนนี้ แล้วนำไปใช้กับเอกสารใหม่แต่ละฉบับ bundle จะจัดเก็บคีย์ที่เหลือเป็นพารามิเตอร์ของ container เพื่อให้ engine ใช้งาน

`artisan`

มีผลเฉพาะเมื่อ nextpdf/artisan ถูกติดตั้งและตรวจพบ

คีย์	ชนิด	ค่าเริ่มต้น
`artisan.chrome_binary`	scalar	`null`
`artisan.render_timeout`	integer	`30`
`artisan.default_css`	scalar	(ว่าง)
`artisan.no_sandbox`	boolean	`false`
`artisan.max_html_size`	integer	`5000000`

`signature`

มีผลเฉพาะเมื่อ nextpdf/premium ถูกติดตั้ง เมื่อมี bundle และระดับ Pro อยู่ การกำหนดค่าการลงนามที่รองรับคือ baseline B-B profile โหนด level ยอมรับค่า string ด้านล่างเพื่อให้สคีมาเข้ากันได้กับกลุ่มการกำหนดค่า NextPDF ที่กว้างกว่า bundle นี้ให้ความสามารถการลงนาม B-B ส่วนโปรไฟล์นอกเหนือจาก B-B มีบันทึกแยกไว้ในเอกสาร NextPDF Premium และไม่ได้อ้างถึงในที่นี้

คีย์	ชนิด	ค่าเริ่มต้น	การตรวจสอบความถูกต้อง
`signature.enabled`	boolean	`false`	—
`signature.certificate`	scalar	`null`	—
`signature.private_key`	scalar	`null`	—
`signature.password`	scalar	(ว่าง)	—
`signature.extra_certs`	รายการของ string	`[]`	—
`signature.level`	enum	`B-B`	ชุดค่าที่ยอมรับ: `B-B`, `B-T`, `B-LT`, `B-LTA` (B-B มอบให้; `B-T`/`B-LT`/`B-LTA` เป็นค่าเพื่อความเข้ากันได้ของสคีมา ไม่ใช่ความสามารถ Pro ที่มอบให้)

compiler pass จะลงทะเบียนบริการ signer เฉพาะเมื่อ signature.enabled เป็น true และ มีการตั้งค่า signature.certificate ไว้ มิฉะนั้นส่วนนี้จะไม่มีผล

`tsa`

การกำหนดค่าไคลเอนต์ Time Stamp Authority (TSA) ที่การลงนาม Pro ใช้เมื่อมีการกำหนดค่าไว้

คีย์	ชนิด	ค่าเริ่มต้น
`tsa.url`	scalar	`null`
`tsa.username`	scalar	(ว่าง)
`tsa.password`	scalar	(ว่าง)
`tsa.cert`	scalar	`null`
`tsa.key`	scalar	`null`
`tsa.timeout`	integer	`30`
`tsa.allow_insecure_http`	boolean	`false`
`tsa.pinned_public_keys`	รายการของ string	`[]`
`tsa.warn_on_key_rotation`	boolean	`true`

bundle จะลงทะเบียนบริการไคลเอนต์ TSA เฉพาะเมื่อมีการตั้งค่า tsa.url ไว้

`ocsp_cache`

คีย์	ชนิด	ค่าเริ่มต้น
`ocsp_cache.enabled`	boolean	`true`
`ocsp_cache.ttl`	integer	`86400`
`ocsp_cache.directory`	scalar	`null`

`messenger`

การตั้งค่าสำหรับการสร้างแบบอะซิงโครนัส ซึ่งจะใช้เมื่อ symfony/messenger ถูกติดตั้ง

คีย์	ชนิด	ค่าเริ่มต้น
`messenger.transport`	scalar	`async`
`messenger.timeout`	integer	`120`
`messenger.retries`	integer	`3`

การกำหนดค่าสำหรับอ้างอิง

ไฟล์การกำหนดค่าที่แสดงทุกส่วนพร้อมค่าเริ่มต้น:

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

บริการและ alias ของ container

bundle จะโหลดนิยามบริการจาก config/services.php ตารางด้านล่างสะท้อนไฟล์นั้นทุกประการ

Service id	แชร์	สาธารณะ	หมายเหตุ
`NextPDF\Typography\FontRegistry`	ใช่	—	สร้างขึ้นจาก `nextpdf.fonts_path`; logger ที่เลือกใช้ได้ตาม PHP Standard Recommendation 3 (PSR-3)
`NextPDF\Contracts\FontRegistryInterface`	(alias)	ใช่	alias ของ `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	ใช่	—	least-recently-used (LRU) แบบมีขอบเขต; ติดแท็ก `kernel.reset` (`reset`)
`NextPDF\Core\DocumentFactory`	ใช่	—	ใช้ registry ทั้งสองร่วมกัน
`NextPDF\Contracts\DocumentFactoryInterface`	(alias)	ใช่	alias ของ `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	ใช่	ใช่	อ่าน `defaults`, `pdfa` และ `artisan` เป็นพารามิเตอร์
`NextPDF\Contracts\PdfDocumentInterface`	ไม่	ใช่	factory `[PdfFactory, create]`
`NextPDF\Core\Document`	(alias)	—	alias ของ `PdfDocumentInterface`
`nextpdf.document`	(alias)	ใช่	alias ของ `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	ใช่	ตัวช่วยแบบไม่มีสถานะ

bundle ยังลงทะเบียน contract binding ของ EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) เฉพาะ เมื่อมีคลาส implementation ของ Premium ที่เกี่ยวข้องอยู่ แต่ละบริการเป็นแบบไม่แชร์ ผู้เรียกจึงได้รับอินสแตนซ์ใหม่ทุกครั้ง สถานะของ parser ในแต่ละการเรียกจะไม่รั่วไหลข้ามคำขอ

แบบแชร์เทียบกับแบบไม่แชร์

nextpdf.document (และ alias ของบริการนี้) เป็นแบบ non-shared: ทุกครั้งที่ resolve จาก container จะได้เอกสารคนละฉบับ ตาม PHP Standard Recommendation 11 (PSR-11) container อาจคืนค่าที่แตกต่างกันในการเรียก get() ต่อเนื่องกันด้วยตัวระบุเดียวกัน ดู PSR-11 §1.1.2 font registry เป็นแบบแชร์และถูกล็อกหลังจากการ warmup ข้อมูลโครงสร้างของฟอนต์จะถูกแยกวิเคราะห์เพียงครั้งเดียวต่อหนึ่งโพรเซส และไม่สามารถเปลี่ยนแปลงระหว่างคำขอได้

บริการ FontRegistry และ ImageRegistry รับ Psr\Log\LoggerInterface ที่เลือกใช้ได้ Symfony จะ bind ด้วย nullOnInvalid() โดย logger ยังคงเป็นองค์ประกอบร่วมที่เลือกใช้ได้และสับเปลี่ยนได้ สอดคล้องกับสัญญา logger ของ PSR-3

Autowiring

PdfFactory, PdfResponse, document factory interface และ font registry interface เป็นแบบสาธารณะ องค์ประกอบเหล่านี้สามารถดึงจาก container หรือระบุ type-hint ใน controller และบริการที่ใช้ autowiring ได้ การฉีดผ่าน constructor ของ NextPDF\Symfony\Service\PdfFactory เป็นจุดเริ่มต้นที่แนะนำ

กรณีขอบและข้อควรระวัง

ตั้งค่า pdfa โดยไม่มี Pro — ค่าจะถูกจัดเก็บแต่ถูกละเว้น PdfFactory จะใช้ Portable Document Format/Archival (PDF/A) เฉพาะเมื่อตรวจพบส่วนขยาย Pro ในขณะ compile
image_cache_mb: 0 — ใช้ได้; ปิดใช้งานแคช LRU ของรูปภาพ ค่าติดลบจะถูกปฏิเสธในขณะ build
signature.enabled: true โดยไม่มี signature.certificate — บริการ signer จะไม่ถูกลงทะเบียน; การกำหนดค่าจะไม่มีผลอย่างเงียบๆ ตามที่ออกแบบไว้
ตัวยึดตำแหน่ง %kernel.*% — ค่าเริ่มต้นของ fonts_path และ cache_path ใช้พารามิเตอร์ของ Symfony container; แทนที่ด้วยพาธสัมบูรณ์เฉพาะเมื่อจำเป็นต้องใช้พาธตามตัวอักษรเท่านั้น

ความสอดคล้อง

แต่ละแถวแสดงข้ออ้างเชิงบรรทัดฐานในหน้านี้ ซึ่งผูกกับ reference_id แบบ 64-hex เต็มจากคลัง standards development organization (SDO) ที่มีการควบคุมการเข้าถึง แหล่งที่มา รวมถึง manifest ของคลังและช่องทางการดึงข้อมูล ระบุไว้ในไฟล์ _sidecars/rag-citations.yaml นี้

ข้อกำหนด	ข้อ	reference_id	ข้ออ้าง
PSR-11	`psr_11_container#1.1.2.p3.b`		get() อาจคืนค่าที่แตกต่างกันในแต่ละการ resolve
PSR-3	`psr_3_logger#x3.p17`		องค์ประกอบร่วม LoggerInterface ที่เลือกใช้ได้

บริบทเชิงพาณิชย์

ส่วน signature และ tsa จะมีผลเฉพาะเมื่อ nextpdf/premium (Pro) ถูกติดตั้ง ความสามารถ Pro ที่เลือกใช้ได้นี้ไม่จำเป็นต้องเปลี่ยนแปลงโค้ดใน Core bundle ที่อธิบายไว้ในที่นี้ ดูได้ที่ </get-license/?intent=symfony-pro>

ดูเพิ่มเติม

/integrations/symfony/install/ — ติดตั้งและลงทะเบียน bundle
/integrations/symfony/overview/ — ดูสรุปความสามารถ
/integrations/symfony/production-usage/ — ความปลอดภัยของ worker และรูปแบบการทำงานแบบอะซิงโครนัส
/integrations/symfony/boot-and-discovery/ — ดูวิธีที่การกำหนดค่าถูก resolve ระหว่างการบูต