การบูตและการค้นพบ NextPDF ใน Symfony

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

เคอร์เนลลงทะเบียน NextPdfBundle จากนั้นส่วนขยาย Dependency Injection (DI) ของบันเดิลจะโหลด services.php และประมวลผลต้นไม้การกำหนดค่าให้เป็นพารามิเตอร์ของคอนเทนเนอร์ ต่อจากนั้น compiler pass หนึ่งตัวจะเชื่อมต่อส่วนขยายทางเลือกและการอุ่นเครื่องฟอนต์

วิธีที่ Symfony Flex ตรวจพบบันเดิล

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

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

ในแอปพลิเคชัน Symfony Flex คำใบ้นี้จะเพิ่ม NextPDF\Symfony\NextPdfBundle ลงใน config/bundles.php สำหรับทุกสภาพแวดล้อม (all) หากไม่มี Flex ให้เพิ่มบันเดิลด้วยตนเองใน config/bundles.php Symfony จัดทำเอกสารโมเดลการลงทะเบียนบันเดิลไว้ที่ (https://symfony.com/doc/current/bundles.html) คลาสต่างๆของบันเดิลจะออโตโหลดภายใต้คำนำหน้า PHP Standard Recommendation (PSR)-4 คือ NextPDF\Symfony\ ซึ่งแมปไปยัง src/Symfony/ ออโตโหลดเดอร์แบบ PSR-4 จะแมปคำนำหน้าเนมสเปซไปยังไดเรกทอรีฐานนั้น (PSR-4 §2)

ลำดับการบูต

ลำดับการบูตซึ่งตรวจสอบเทียบกับซอร์สของบันเดิลแล้ว:

1. เคอร์เนลลงทะเบียนบันเดิล Kernel::registerBundles() อ่าน config/bundles.php และสร้างอินสแตนซ์ของ NextPDF\Symfony\NextPdfBundle ซึ่งสืบทอดจาก Symfony\Component\HttpKernel\Bundle\Bundle
2. การบิลด์บันเดิล NextPdfBundle::build() เรียกเมท็อดของคลาสพาเรนต์ แล้วลงทะเบียน compiler pass หนึ่งตัวคือ OptionalExtensionPass NextPdfBundle::getPath() คืนค่ารากของแพ็กเกจ
3. การโหลดส่วนขยาย ส่วนขยาย DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (ใช้นามแฝง nextpdf) เรียกใช้ processConfiguration() กับ Configuration แล้วจัดเก็บค่าที่ประมวลผลแล้วเป็นพารามิเตอร์ของคอนเทนเนอร์ nextpdf.* จากนั้นโหลด config/services.php ผ่าน PhpFileLoader
4. การตรวจสอบส่วนขยายที่จำเป็น NextPdfExtension::load() ปิดท้ายด้วยการยืนยันว่ามี ext-mbstring และ ext-zlib อยู่ และจะล้มเหลวทันทีหากไม่มี
5. compiler pass ทำงาน ระหว่างการคอมไพล์คอนเทนเนอร์ OptionalExtensionPass::process() จะกำหนดค่าธงความพร้อมใช้งานของส่วนขยายบน PdfFactory ลงทะเบียนผู้ลงนามและไคลเอนต์ของผู้ออกการประทับเวลา (TSA) ตามเงื่อนไข และกำหนดให้รีจิสทรีฟอนต์อุ่นเครื่องและล็อก
6. คอนเทนเนอร์ถูกคอมไพล์และแคช Symfony เขียนคอนเทนเนอร์ที่คอมไพล์แล้ว cache:warmup ดำเนินขั้นตอนนี้ก่อนที่ทราฟฟิกจะมาถึงแอปพลิเคชัน

คอมไพเลอร์พาส (Compiler Pass)

บันเดิลลงทะเบียน pass เพียงตัวเดียว คือ NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass ใน NextPdfBundle::build() pass นี้ทำงานในกลุ่ม pass ค่าเริ่มต้น (before-optimization) และดำเนินงานสี่ขั้นตอน แต่ละขั้นตอนมีการป้องกันไว้ จึงข้ามการทำงานเมื่อไม่มีอินพุตที่ต้องใช้:

• ธงส่วนขยาย — เพิ่มการเรียกเมท็อด setArtisanAvailable(...) และ setProAvailable(...) ลงในนิยามของ PdfFactory ค่าเหล่านี้ได้จากการตรวจสอบ class_exists ณ เวลาคอมไพล์สำหรับ Artisan browser factory และคลาส Pro PDF/A
• การลงทะเบียนผู้ลงนาม — ลงทะเบียน certificate-info factory และเซอร์วิสผู้ลงนามสำหรับโปรไฟล์พื้นฐาน B-B เมื่อมี nextpdf.signature ซึ่ง enabled เป็น true และตั้งค่าใบรับรองไว้แล้ว
• ไคลเอนต์ TSA — ลงทะเบียนเซอร์วิสไคลเอนต์ TSA เมื่อ nextpdf.tsa มี Uniform Resource Locator (URL)
• การอุ่นเครื่องฟอนต์ — เพิ่มการเรียกเมท็อด warmup() และ lock() ลงในนิยามรีจิสทรีฟอนต์เมื่อ nextpdf.preload_fonts ไม่ว่าง

การผูกเซอร์วิสในคอนเทนเนอร์

config/services.php เป็นไฟล์ที่นิยามเซอร์วิสต่างๆ เซอร์วิสเอกสาร nextpdf.document (มีนามแฝงเป็น NextPDF\Contracts\PdfDocumentInterface และ NextPDF\Core\Document) เป็นเซอร์วิสแบบ ไม่ใช้ร่วมกัน: ทุกครั้งที่เรียกขอจะได้เอกสารชุดใหม่ PSR-11 อนุญาตพฤติกรรมนี้ไว้อย่างชัดเจน การเรียก get() ต่อเนื่องกันสำหรับ id เดียวกันอาจคืนค่าที่แตกต่างกันได้ (PSR-11 §1.1.2) รีจิสทรีฟอนต์ใช้ร่วมกันและจะถูกล็อกหลังการอุ่นเครื่อง รีจิสทรีรูปภาพใช้ร่วมกันและติดแท็ก kernel.reset ดูตารางฉบับเต็มได้ที่ /integrations/symfony/configuration/

ลำดับการประมวลผลค่าการกำหนดค่า

1. ค่าเริ่มต้นในตัวจาก Configuration (getConfigTreeBuilder())
2. ค่าที่แอปพลิเคชันกำหนดทับใน config/packages/nextpdf.yaml รวมถึงค่าที่กำหนดทับตามสภาพแวดล้อมภายใต้ config/packages/<env>/
3. Symfony แทนค่าตัวยึดพารามิเตอร์ %kernel.*% ตัวอย่างเช่น fonts_path มีค่าเริ่มต้นเป็น %kernel.project_dir%/resources/fonts
4. NextPdfExtension::load() เขียนผลลัพธ์ที่ผสานแล้วลงในพารามิเตอร์ของคอนเทนเนอร์ nextpdf.* ซึ่ง services.php และ compiler pass นำไปใช้

ค่าที่ไม่ถูกต้องจะทำให้ขั้นตอน 1–2 ล้มเหลวพร้อมกับ InvalidConfigurationException ของ Symfony

การตรวจวินิจฉัย

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

คำสั่งแรกแสดงรายการเซอร์วิสที่ลงทะเบียนไว้ คำสั่งที่สองพิมพ์การกำหนดค่าที่ผสานแล้ว คำสั่งที่สามสร้างคอนเทนเนอร์ใหม่และรันการตรวจสอบส่วนขยาย ณ เวลาคอมไพล์อีกครั้ง

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

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

ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)	ข้ออ้าง
PSR-11	psr_11_container#1.1.2.p3.b		ผลการแก้ค่าจากคอนเทนเนอร์อาจแตกต่างกันในแต่ละครั้งที่เรียก
PSR-4	psr_4_autoload#x1.x2.p5		การแมปคำนำหน้าเนมสเปซไปยังไดเรกทอรีฐาน

ดูเพิ่มเติม

• /integrations/symfony/integration/ — เอกสารอ้างอิงการเชื่อมต่อแบบครบวงจร
• /integrations/symfony/install/ — การติดตั้งและการลงทะเบียน
• /integrations/symfony/configuration/ — ต้นไม้การกำหนดค่าฉบับเต็มและตารางเซอร์วิส
• /integrations/symfony/overview/ — สรุปความสามารถ