การแก้ไขปัญหา NextPDF Symfony bundle

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

ปัญหาส่วนใหญ่มักเกิดจากหนึ่งในสี่ส่วนนี้ ได้แก่ การค้นพบ การตรวจสอบคอนฟิก การเชื่อมต่อคอนเทนเนอร์ หรือการกำหนดเส้นทางของ Messenger แต่ละหัวข้อจะจับคู่อาการกับพฤติกรรมของ bundle ที่อยู่เบื้องหลัง และให้คำสั่งคอนโซลสำหรับยืนยันการแก้ไข

ไม่ได้ลงทะเบียน bundle

อาการ: ไม่สามารถ autowire PdfFactory ได้ หรือ debug:container nextpdf ไม่คืนค่าใด ๆ

สาเหตุ: อาจยังไม่ได้เพิ่ม bundle ลงใน config/bundles.php Flex อาจยังไม่ได้ทำงาน หรือแอปพลิเคชันอาจไม่ได้ใช้ Flex

วิธีแก้ไข:

php bin/console debug:container nextpdf

หากคำสั่งไม่คืนค่าบริการใด ๆ ให้เพิ่ม bundle ด้วยตนเอง:

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

ไฟล์ composer.json ของ bundle มีคำใบ้สำหรับการลงทะเบียนอัตโนมัติอยู่ภายใต้ extra.symfony.bundles คำใบ้นี้ใช้ได้เฉพาะกับแอปพลิเคชันที่เปิดใช้ Flex เท่านั้น

การบูตล้มเหลวเพราะไม่มี PHP extension

อาการ: เคอร์เนลโยน RuntimeException ที่กล่าวถึง ext-mbstring หรือ ext-zlib ระหว่างการบูต

สาเหตุ: ปัญหานี้มาจาก NextPdfExtension::guardRequiredExtensions() ซึ่งเป็นกลไกป้องกันแบบ fail-fast ที่ bundle ตั้งใจให้ทำงาน กลไกนี้ไม่ใช่ข้อบกพร่อง

วิธีแก้ไข: เปิดใช้ extension ที่ระบุใน php.ini แล้วรีสตาร์ตรันไทม์ จากนั้นยืนยันด้วย:

php -m | grep -E 'mbstring|zlib'

คอนฟิกถูกปฏิเสธในช่วง build

อาการ: Symfony โยน Symfony\Component\Config\Definition\Exception\InvalidConfigurationException ระหว่าง cache:clear หรือ cache:warmup

สาเหตุ: มีค่าบางรายการอยู่นอกขอบเขตที่สคีมากำหนด Configuration.php กำหนดข้อจำกัดเหล่านี้ไว้:

• page_format ต้องเป็นค่าใดค่าหนึ่งใน A4, A3, A5, Letter, Legal, Tabloid
• orientation ต้องเป็น P หรือ L
• unit ต้องเป็นค่าใดค่าหนึ่งใน pt, mm, cm, in
• pdfa ต้องเป็น null, 4, 4e, หรือ 4f
• image_cache_mb ต้องเป็น >= 0

วิธีแก้ไข: แสดงคอนฟิกที่ผสานแล้ว จากนั้นแก้ไขคีย์ที่ทำให้ล้มเหลว:

php bin/console debug:config nextpdf

PDF/A หรือการลงลายเซ็นไม่มีผล

อาการ: ตั้งค่าส่วน pdfa หรือ signature แล้ว แต่ผลลัพธ์ยังเป็นไฟล์ Portable Document Format (PDF) ธรรมดา

สาเหตุ: ความสามารถเหล่านี้ต้องใช้ nextpdf/premium โดยในช่วง compile PdfFactory จะใช้ PDF/A ก็ต่อเมื่อตรวจพบส่วนขยาย Pro เท่านั้น ส่วน compiler pass จะลงทะเบียน signer ก็ต่อเมื่อ signature.enabled เป็น true และ ตั้งค่า signature.certificate แล้วเท่านั้น

วิธีแก้ไข: ยืนยันว่าติดตั้ง Premium แล้วและมีบริการ signer อยู่:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

หากไม่มี Premium อยู่ bundle จะเก็บคอนฟิกไว้ แต่จงใจปล่อยให้คอนฟิกนั้นไม่ทำงาน ความสามารถด้านการลงลายเซ็นของ bundle ที่ระบุไว้ในเอกสารเมื่อใช้ร่วมกับ Pro คือโปรไฟล์พื้นฐาน B-B เอกสาร NextPDF Premium ครอบคลุมโปรไฟล์ที่นอกเหนือจาก B-B

การเรนเดอร์ด้วย Chrome ไม่ทำงาน

อาการ: คอนฟิก artisan ถูกละเว้น

สาเหตุ: การเรนเดอร์ผ่าน Chrome DevTools Protocol (CDP) ต้องใช้ nextpdf/artisan โดย compiler pass จะตรวจหาส่วนขยายนี้ด้วย class_exists ในช่วง compile หากไม่มีส่วนขยายนี้อยู่ ตัวเรนเดอร์จะไม่ถูกเชื่อมต่อ

วิธีแก้ไข:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

การตรวจหานี้เกิดขึ้นระหว่างการ compile คอนเทนเนอร์ หลังจากติดตั้งส่วนขยายแล้ว ให้รัน cache:clear ใหม่

Messenger handler ไม่เคยถูกเรียก

อาการ: dispatch GeneratePdfMessage แล้ว แต่ไม่มีการเขียน PDF ออกมา

สาเหตุและวิธีแก้ไข:

• ข้อความไม่ได้ถูกกำหนดเส้นทาง — เพิ่มรายการกำหนดเส้นทางที่แมป NextPDF\Symfony\Message\GeneratePdfMessage ไปยัง transport ใน config/packages/messenger.yaml จากนั้นรัน worker (php bin/console messenger:consume <transport>)
• Builder ไม่อยู่ใน locator — handler จะดึง builder จาก locator แบบ PHP Standards Recommendation 11 (PSR-11) โดยใช้ id ที่เป็น class-string ตัวระบุของคอนเทนเนอร์คือสตริงที่ระบุรายการหนึ่งได้อย่างไม่ซ้ำกัน (PSR-11 §1.1.2) หาก locator ไม่ได้ลงทะเบียนคลาส builder ไว้ handler จะโยน RuntimeException ที่ระบุว่า builder ที่กำหนดค่าไว้ต้อง implement PdfBuilderInterface ให้ลงทะเบียน builder แล้วอ้างอิง builder นั้นจาก locator

ตรวจสอบการกำหนดเส้นทางและ locator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

ข้อความถูกปฏิเสธขณะ dispatch ด้วย InvalidArgumentException

อาการ: การสร้าง GeneratePdfMessage โยน InvalidArgumentException

สาเหตุ: data transfer object (DTO) ของข้อความจะตรวจสอบความถูกต้องของอินพุต กฎการปฏิเสธที่ยืนยันแล้วมีดังนี้:

• พาธปลายทางว่างเปล่า หรือพาธที่มี null byte
• รูปแบบ stream-wrapper (เช่น php://...)
• เซกเมนต์ path-traversal .. (ตัวคั่นแบบ POSIX หรือ Windows)
• พาธปลายทางที่ไม่ลงท้ายด้วย .pdf (ไม่สนใจตัวพิมพ์ใหญ่เล็ก)
• รายการ builderClass ที่ไม่ใช่ชื่อคลาสที่ถูกต้องตามไวยากรณ์

วิธีแก้ไข: ส่งพาธในระบบไฟล์แบบสัมบูรณ์ที่ลงท้ายด้วย .pdf และชื่อคลาส builder แบบ fully qualified ที่มีอยู่จริง

เอกสารมีข้อมูลเก่าค้างอยู่

อาการ: PDF ที่สร้างขึ้นมีเนื้อหาจากคำขอครั้งก่อน

สาเหตุ: worker ที่ทำงานต่อเนื่องเป็นเวลานานถืออินสแตนซ์ Document ไว้ข้ามคำขอ บริการเอกสารถูกตั้งให้เป็นแบบ non-shared เพื่อป้องกันปัญหานี้โดยเฉพาะ

วิธีแก้ไข: เรียก PdfFactory::create() ภายในเมธอดที่อยู่ในขอบเขตของคำขอ อย่าเก็บเอกสารที่คืนกลับมาไว้ในบริการที่ใช้ร่วมกัน

อ้างอิงคำสั่งวินิจฉัย

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

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

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

ข้อกำหนด (Spec)	อนุประโยค	รหัสอ้างอิง (reference_id)	ข้อกล่าวอ้าง
PSR-11	psr_11_container#1.1.2.p4		สัญญาตัวระบุของ Container has()/get()

ดูเพิ่มเติม

• /integrations/symfony/install/ — การติดตั้งและการลงทะเบียน
• /integrations/symfony/configuration/ — สคีมาแบบเต็มและข้อจำกัด
• /integrations/symfony/boot-and-discovery/ — ลำดับการค้นพบและการบูต
• /integrations/symfony/security-and-operations/ — ส่วนหัวความปลอดภัยและการตรวจสอบพาธ