การติดตั้ง bundle ของ NextPDF สำหรับ Symfony

ภาพรวมโดยย่อ

ติดตั้ง bundle ด้วย Composer หากแอปพลิเคชันของคุณใช้ Symfony Flex bundle จะลงทะเบียนตัวเองโดยอัตโนมัติ หากไม่มี Flex ให้ลงทะเบียนใน config/bundles.php เพียงครั้งเดียว

ข้อกำหนด

ไฟล์ composer.json ของ bundle กำหนดข้อจำกัดเวอร์ชันต่อไปนี้

dependency	ข้อจำกัดเวอร์ชัน
php	>=8.4 <9.0
nextpdf/core	^3.0 || ^5.2
symfony/framework-bundle	^7.2
symfony/dependency-injection	^7.2
symfony/config	^7.2
symfony/http-foundation	^7.2
psr/log	^3.0

bundle ยังตรวจสอบ PHP extension สองรายการระหว่างขั้นตอนการสร้าง container ได้แก่ ext-mbstring และ ext-zlib PHP runtime ที่รองรับทุกรุ่นเปิดใช้งาน extension ทั้งสองรายการไว้แล้ว หากขาด extension รายการใดรายการหนึ่ง การตรวจสอบจะหยุดทำงานทันทีพร้อมข้อความที่ชัดเจน

แพ็กเกจเสริม

ไฟล์ composer.json ของ bundle ประกาศแพ็กเกจต่อไปนี้ไว้ภายใต้ suggest ให้เพิ่มแพ็กเกจเหล่านี้เมื่อต้องการพฤติกรรมที่แพ็กเกจนั้นรองรับ

แพ็กเกจ	ความสามารถที่เพิ่ม
nextpdf/artisan	เรนเดอร์ HTML ผ่าน Chrome CDP ระบบจะตรวจพบโดยอัตโนมัติระหว่างคอมไพล์
nextpdf/premium	การจัดเก็บถาวรแบบ PDF/A และการลงลายเซ็นดิจิทัล (ติดตั้ง Pro tier) ระบบจะตรวจพบโดยอัตโนมัติระหว่างคอมไพล์
symfony/messenger	สร้าง PDF แบบ asynchronous ผ่าน Messenger handler

ติดตั้งด้วย Composer

composer require nextpdf/symfony

bundle ใช้ autoload ภายใต้ prefix แบบ PHP Standard Recommendation 4 (PSR-4) คือ NextPDF\Symfony\ ซึ่ง map ไปยัง src/Symfony/ การ map นี้ประกาศไว้ใน composer.jsonautoload.psr-4 โดย autoloader ที่ Composer สร้างขึ้นจะ map prefix ของ namespace ไปยัง base directory ดังกล่าว ตามที่ PSR-4 §2 กำหนด

ลงทะเบียน bundle

Symfony Flex (แนะนำ)

bundle มี hint สำหรับการลงทะเบียนอัตโนมัติในไฟล์ composer.json ดังนี้

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

เมื่อแอปพลิเคชันเปิดใช้งาน Flex รายการนี้จะเพิ่ม bundle ลงใน config/bundles.php สำหรับทุก environment (all) โดยอัตโนมัติ คุณไม่จำเป็นต้องแก้ไขไฟล์ด้วยตนเอง โปรดดูรูปแบบการลงทะเบียนในเอกสาร bundle อย่างเป็นทางการของ Symfony (https://symfony.com/doc/current/bundles.html)

การลงทะเบียนด้วยตนเอง (ไม่มี Flex)

หากแอปพลิเคชันของคุณไม่ได้ใช้ Symfony Flex ให้เพิ่ม bundle ลงใน config/bundles.php ด้วยตนเอง

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

คลาสของ bundle คือ NextPDF\Symfony\NextPdfBundle คลาสนี้สืบทอดจากคลาสฐาน Symfony\Component\HttpKernel\Bundle\Bundle ของ Symfony เมท็อด getPath() ของ bundle จะคืนค่า root ของแพ็กเกจ ส่วนเมท็อด build() จะลงทะเบียน OptionalExtensionPass เป็น compiler pass

จัดเตรียมไฟล์การกำหนดค่า

alias สำหรับการกำหนดค่าของ bundle คือ nextpdf ให้สร้าง config/packages/nextpdf.yaml เมื่อเผยแพร่แล้ว Flex recipe จะเพิ่มสำเนาค่าเริ่มต้นไว้ที่ตำแหน่งนี้ให้คุณ ไฟล์แบบย่อที่สุดที่ใช้ค่าเริ่มต้นในตัวทั้งหมดมีลักษณะดังนี้

nextpdf: ~

ทุกคีย์มีค่าเริ่มต้น ดังนั้นการกำหนดค่าแบบว่างจึงใช้งานได้ หน้า /integrations/symfony/configuration/ อธิบายโครงสร้างการกำหนดค่าฉบับเต็มไว้แล้ว

ตรวจสอบการติดตั้ง

ตรวจสอบว่า container มองเห็นบริการของ bundle ได้

php bin/console debug:container nextpdf

คุณควรเห็นบริการซึ่งรวมถึง alias nextpdf.document และ NextPDF\Symfony\Service\PdfFactory หากต้องการตรวจสอบการกำหนดค่าที่ resolve แล้ว ให้รัน

php bin/console debug:config nextpdf

คำสั่งนี้จะแสดงโครงสร้างการกำหนดค่าที่ผสานแล้ว ได้แก่ ค่าที่คุณ override รวมกับค่าเริ่มต้น

กรณีพิเศษและข้อควรระวัง

• ช่วงข้อจำกัดเวอร์ชันของ core — bundle ยอมรับ nextpdf/core^3.0 || ^5.2 Composer จะ resolve เวอร์ชันที่ตรงตามเงื่อนไขของ dependency graph ส่วนที่เหลือในแอปพลิเคชันของคุณ หากต้องการเวอร์ชันเอนจินที่แน่นอน ให้ pin major version เดียวไว้ใน composer.json ของแอปพลิเคชันของคุณ
• การตรวจสอบ extension ที่ขาดหายไป — หาก php bin/console หยุดทำงานระหว่างบูตพร้อมข้อความเกี่ยวกับ ext-mbstring หรือ ext-zlib ให้เปิดใช้งาน extension ที่ระบุใน php.ini พฤติกรรมแบบ fail-fast นี้เป็นไปตามที่ตั้งใจ ไม่ใช่ข้อบกพร่องของ bundle
• Flex ไม่ได้ลงทะเบียน bundle — ให้ล้างแคชของ Composer แล้วติดตั้งใหม่ หากไม่ได้ใช้ Flex ให้ทำตามขั้นตอนการกำหนด config/bundles.php ด้วยตนเอง

ความสอดคล้องตามมาตรฐาน

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

มาตรฐาน	ข้อกำหนด	รหัสอ้างอิง (reference_id)	ข้อความที่อ้าง
PSR-4	psr_4_autoload#x1.x2.p5		การ map prefix ของ namespace ไปยังไดเรกทอรีของ autoloader

ดูเพิ่มเติม

• /integrations/symfony/overview/ — สิ่งที่ bundle มอบให้
• /integrations/symfony/configuration/ — โครงสร้างการกำหนดค่าฉบับเต็มและตารางบริการ
• /integrations/symfony/quickstart/ — controller ตัวแรกที่รันได้
• /integrations/symfony/boot-and-discovery/ — ลำดับการ discovery และการบูตโดยละเอียด