คู่มือช่วยตัดสินใจเลือกการผสานการทำงาน

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

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

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

เหตุใดเรื่องนี้จึงสำคัญ

การเลือกการผสานการทำงานผิดมีต้นทุนสูงที่มักไม่เห็นทันที หากเลือกตัวเรนเดอร์เบราว์เซอร์ระยะไกลทั้งที่เอนจินภายในกระบวนการสามารถเรนเดอร์เอกสารได้อย่างถูกต้อง คุณจะเพิ่มการเรียกข้ามเครือข่ายและการพึ่งพาความพร้อมใช้งานให้กับ PDF ทุกไฟล์ หากเลือกเอนจินภายในกระบวนการสำหรับเอกสารที่จำเป็นต้องใช้เอนจินจัดเลย์เอาต์แบบเบราว์เซอร์เต็มรูปแบบอย่างแท้จริง คุณจะได้ไฟล์ที่ผิดเพี้ยนแบบสังเกตได้ยาก แพ็กเกจที่คุณนำมาใช้เป็นตัวกำหนดความหน่วง รูปแบบความล้มเหลว และขอบเขตการดำเนินงาน ดังนั้นการตัดสินใจนี้จึงควรถูกกำหนดอย่างชัดเจน

สรุปฉบับย่อ

เริ่มต้นด้วยเอนจินหลัก ส่วนอื่นทั้งหมดเป็นส่วนเสริม หากเอนจินภายในกระบวนการเรนเดอร์เอกสารของคุณได้อย่างถูกต้อง คุณไม่ต้องใช้แพ็กเกจตัวเรนเดอร์ใดเลย
บริดจ์เฟรมเวิร์กเลือกตามเฟรมเวิร์กของคุณ ไม่ใช่ตามเอกสารของคุณ การผสานการทำงานกับ Laravel, Symfony และ CodeIgniter มีไว้เพื่อมอบฟาซาดหรือแฟกทอรี การตอบกลับแบบ PDF การสร้างแบบเข้าคิว และการค้นพบอัตโนมัติ — สิ่งเหล่านี้ไม่ได้เปลี่ยนสิ่งที่เอนจินเรนเดอร์ได้
ใช้ตัวเรนเดอร์เฉพาะเมื่อความเที่ยงตรงของ CSS จำเป็นต้องใช้เบราว์เซอร์ Artisan (Chrome ภายในเครื่อง) และ Cloudflare (เบราว์เซอร์ที่เอดจ์) มีไว้สำหรับกรณีนั้นโดยเฉพาะ ส่วน Gotenberg มีไว้รองรับเอกสาร Office
ใช้ Connect เมื่อผู้เรียกเป็นบริการหรือ AI agent ไม่ใช่การเรียกแบบ PHP โดยเปิดให้เข้าถึงเอนจินผ่าน MCP, REST และ gRPC พร้อมประตูยืนยันโดยมนุษย์สำหรับการดำเนินการที่อันตราย

NextPDF วางแนวทางเรื่องนี้อย่างไร

ระบบนิเวศถูกออกแบบเป็นลำดับชั้นอย่างตั้งใจ เพื่อให้แต่ละแพ็กเกจมีหน้าที่เดียว เอนจินหลักเรนเดอร์ PDF ภายในกระบวนการ บริดจ์เฟรมเวิร์กปรับเอนจินนั้นให้เข้ากับรูปแบบการใช้งานเฉพาะของเฟรมเวิร์ก แพ็กเกจตัวเรนเดอร์ส่งต่อการจัดเลย์เอาต์ HTML หรือ Office ให้กับเอนจินภายนอกเมื่อเอนจินภายในกระบวนการไม่ใช่เครื่องมือที่เหมาะสม Connect เปลี่ยนเอนจินให้เป็นบริการบนเครือข่าย ไม่มีแพ็กเกจใดในกลุ่มนี้ทับซ้อนความรับผิดชอบของอีกแพ็กเกจหนึ่ง จึงทำให้การตัดสินใจจัดการได้ง่าย คุณไม่ได้กำลังเลือกระหว่างเครื่องมือที่แข่งขันกัน แต่กำลังประกอบเครื่องมือที่เสริมกัน

ให้ตัดสินใจจากกรณีการใช้งาน ตารางนี้จับคู่แต่ละสถานการณ์กับแพ็กเกจที่เหมาะสม และระบุข้อแลกเปลี่ยนที่คุณยอมรับ

กรณีการใช้งาน	แพ็กเกจที่เหมาะสม	สิ่งที่แพ็กเกจมอบให้จริง	ข้อแลกเปลี่ยนที่คุณยอมรับ
PDF ในแอป Laravel	`nextpdf/laravel`	เซอร์วิสโพรไวเดอร์ที่ค้นพบอัตโนมัติ ฟาซาด `Pdf` `PdfResponse` (แบบฝังในหน้า/ดาวน์โหลด/สตรีม พร้อมส่วนหัวตาม OWASP) งาน `GeneratePdfJob` แบบเข้าคิวพร้อม tries/timeout/backoff และรีจิสทรีที่ล็อกไว้ซึ่งปลอดภัยกับ Octane	การพึ่งพา Laravel 12 ความสามารถของเอนจินไม่เปลี่ยนแปลง
PDF ในแอป Symfony	`nextpdf/symfony`	บันเดิลที่ลงทะเบียนอัตโนมัติ `PdfFactory` ที่ฉีดได้ `PdfResponse` และตัวจัดการ Messenger เสริมสำหรับการสร้างแบบอะซิงโครนัส	การพึ่งพาบันเดิล Symfony 7.2 ความสามารถไม่เปลี่ยนแปลง
PDF ในแอป CodeIgniter 4	`nextpdf/codeigniter`	`service('pdf')` / `pdf()` ตัวช่วย ไลบรารี `Pdf` ที่ครอบ `Document` แบบใช้แล้วทิ้ง `PdfResponse` และงานแบบเข้าคิวเสริม	การพึ่งพา CodeIgniter 4.6 ความสามารถไม่เปลี่ยนแปลง
เอกสารต้องการ CSS แบบเบราว์เซอร์เต็มรูปแบบ (flex/grid/เว็บฟอนต์) และยังต้องการเส้นทางที่ใกล้กับภายในกระบวนการ	`nextpdf/artisan`	Headless Chrome ผ่าน CDP เรนเดอร์แล้วนำกลับเข้ามาเป็น Form XObject เพื่อให้ข้อความยังคงเลือกได้ พร้อมพูลเบราว์เซอร์	รันไทม์ Chrome และต้นทุน memory/process บนโฮสต์ของคุณ
เอกสาร Office (`.docx`, `.xlsx`) เป็น PDF	`nextpdf/gotenberg`	บริดจ์ PSR-18 ไปยังไมโครเซอร์วิส Gotenberg พร้อมการรับส่งข้อมูลที่เสริมความแข็งแกร่งต่อ SSRF และตรึง IP	บริการ Gotenberg ภายนอกและการพึ่งพาเครือข่าย
HTML→PDF ที่เอดจ์ / ไม่มี Chrome ภายในเครื่อง	`nextpdf/cloudflare`	Cloudflare Browser Rendering ผ่านการรับส่งข้อมูลที่ตรึงไว้ พร้อมตัวสำรอง Chrome ภายในเครื่องแบบเป็นทางเลือก	บัญชี Cloudflare และการพึ่งพาเครือข่าย ตัวสำรองต้องใช้ Artisan
เอนจินถูกเรียกใช้โดยบริการหรือ AI agent	`nextpdf/server` (Connect)	เอนจินเดียวผ่าน MCP (stdio), REST (OpenAPI 3.1) และ gRPC การค้นพบเครื่องมือแบบ soft-dependency ประตูยืนยันโดยมนุษย์สำหรับเครื่องมือที่มีความเสี่ยงสูง	การดำเนินงานในขอบเขตบริการ วินัยการดำเนินการแบบกำหนดผลได้แน่นอน

นี่คือการตัดสินใจสองเรื่องที่เป็นอิสระต่อกัน แต่ผู้คนมักนำมาปนกัน ทั้งนี้ บริดจ์เฟรมเวิร์ก เลือกตามเฟรมเวิร์กที่คุณใช้อยู่แล้ว — จึงไม่ ขยายหรือจำกัดสิ่งที่เอนจินเรนเดอร์ได้ ตัวเรนเดอร์ เลือกตาม เอกสาร คำถามชี้ขาดคือเอนจิน CSS ภายในกระบวนการ เพียงพอหรือไม่ หรือเอกสารจำเป็นต้องใช้เอนจินจัดเลย์เอาต์แบบเบราว์เซอร์อย่างแท้จริง คุณ อาจต้องการบริดจ์เฟรมเวิร์กโดยไม่ต้องมีตัวเรนเดอร์ ต้องการตัวเรนเดอร์โดยไม่ต้องมีบริดจ์ ต้องการทั้งสอง หรือไม่ต้องการเลย การมองทั้งสองเป็นคำถามเดียวคือข้อผิดพลาดในการผสานการทำงาน ที่พบบ่อยที่สุด ซึ่งเป็นเหตุผลที่หน้านี้แยกทั้งสองออกจากกัน

หลักฐานบอกอะไร

หน้านี้เป็น บทบรรณาธิการ — การตัดสินใจกำหนดเส้นทาง — แต่การกำหนดเส้นทางตั้งอยู่บนสิ่งที่แมนิเฟสต์และคลาสหลักของแต่ละแพ็กเกจมีให้จริง

บริดจ์เหล่านี้มีอยู่จริงและอยู่ร่วมกัน แต่ละตัวประกาศการพึ่งพาเฟรมเวิร์กและการลงทะเบียนอัตโนมัติไว้ใน composer.json ของตน (extra.laravel.providers, extra.symfony.bundles, และ Registrar ของ CodeIgniter) แต่ละตัวยังมาพร้อม PdfResponse การผูกเอกสารแบบใช้แล้วทิ้ง และงานแบบเข้าคิวที่เป็นทางเลือก ไม่มีตัวใดเพิ่มความสามารถในการเรนเดอร์ — แต่ละตัวเพียงปรับเอนจินตัวเดียวกัน ตัวเรนเดอร์เหล่านี้มีอยู่จริงและแตกต่างกัน Artisan พึ่งพา chrome-php/chrome และนำ PDF ของ Chrome กลับเข้ามาเป็น Form XObject เพื่อให้ข้อความเลือกได้ Gotenberg และ Cloudflare เป็นบริดจ์ HTTP แบบ PSR-18 พร้อมการรับส่งข้อมูลที่เสริมความแข็งแกร่งต่อ SSRF และตรึง IP อย่างชัดเจน Cloudflare สามารถสำรองไปยัง Artisan ได้เมื่อ Worker เข้าถึงไม่ได้ composer.json ของ Connect ประกาศการรับส่งข้อมูลทั้งสามแบบและโมเดลแบบ soft-dependency ที่เครื่องมือจะปรากฏตามแพ็กเกจเครื่องมือที่ติดตั้งไว้ โดยกำกับด้วยโมเดลความเสี่ยงสี่ระดับพร้อมประตูยืนยันโดยมนุษย์

วิธีที่หน้านี้ช่วยกำหนดเส้นทางให้คุณนั้น มีมาตรฐานรองรับ ในเชิงรูปแบบ: Spec: ISO 24495-1:2023, §5 ระบุว่าผู้อ่านควรสามารถ ตัดสินใจได้อย่างรวดเร็วว่าเนื้อหาตอบโจทย์วัตถุประสงค์ของตนหรือไม่ และ Spec: ISO/IEC/IEEE 26514:2022, §3.x222 กำหนดให้ลิงก์ และการอ้างอิงต้องระบุปลายทางของตัวเอง — ซึ่งเป็นเหตุผลที่ตารางระบุชื่อแพ็กเกจที่เป็นรูปธรรมและข้อแลกเปลี่ยน แทนที่จะ กล่าวอ้างถึง “การผสานการทำงาน” อย่างคลุมเครือ

ตัวอย่างเชิงปฏิบัติ

การตัดสินใจเป็นลำดับของคำถามที่ตรงไปตรงมา ไม่ใช่การเปรียบเทียบคุณสมบัติ ขั้นตอนต่อไปนี้คลี่คลายกรณีที่พบบ่อย

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

ประเด็นสำคัญของโครงสร้างนี้คือ การเรนเดอร์และการเรียกใช้เป็นแกนที่แยกจากกัน การตอบคำถามทั้งสองเป็นเรื่องเดียวกันคือสาเหตุที่ทีมต่างๆลงเอยด้วยตัวเรนเดอร์ระยะไกลที่ไม่จำเป็น หรือบริดจ์ที่ไม่ได้แก้ปัญหาความเที่ยงตรงของตน

ความเข้าใจผิดที่พบบ่อย

ความเข้าใจผิดที่พบมากที่สุดคือ “ต้องมีแพ็กเกจตัวเรนเดอร์เพื่อสร้าง PDF” ซึ่งไม่จริง เอนจินหลักสร้าง PDF ภายในกระบวนการ แพ็กเกจตัวเรนเดอร์มีอยู่เฉพาะสำหรับกรณีเฉพาะที่จำเป็นต้องใช้เอนจินจัดเลย์เอาต์ระดับเบราว์เซอร์ หรือเมื่อต้นทางเป็นเอกสาร Office เมื่อเอนจินภายในกระบวนการสร้างไฟล์ที่ถูกต้องได้อยู่แล้ว การนำตัวเรนเดอร์มาใช้โดยอัตโนมัติจะเพิ่มการพึ่งพารันไทม์และรูปแบบความล้มเหลวโดยไม่ได้ประโยชน์เพิ่ม

ความเข้าใจผิดในด้านกลับกันคือ “บริดจ์เฟรมเวิร์กปลดล็อกความสามารถ” ซึ่งไม่จริง บริดจ์เปลี่ยนวิธีที่คุณ เรียก เอนจิน — ฟาซาด แฟกทอรี การตอบกลับ งานแบบเข้าคิว — ไม่ใช่สิ่งที่เอนจินสามารถ ผลิต ได้ การลงนาม, PDF/A และใบแจ้งหนี้แบบมีโครงสร้างเป็นเรื่องของระดับและเอนจิน ซึ่งเหมือนกันไม่ว่าคุณจะเรียกผ่านบริดจ์หรือเรียกโดยตรง

ข้อจำกัดและขอบเขต

หน้านี้กำหนดเส้นทาง ไม่ได้วัดประสิทธิภาพหรือจัดอันดับ หน้านี้ระบุสิ่งที่แต่ละแพ็กเกจมอบให้และข้อแลกเปลี่ยน การเลือกระหว่างแพ็กเกจเหล่านั้นเป็นการตัดสินใจของคุณตามข้อจำกัดของคุณเอง
ความสามารถของแพ็กเกจอ่านจากแมนิเฟสต์และคลาสหลักของแพ็กเกจ ณ ช่วงเวลาหนึ่ง ให้ถือเอกสารของแพ็กเกจนั้นเองเป็นแหล่งข้อมูลที่เชื่อถือได้สำหรับ API ปัจจุบัน คู่มือนี้คือแผนที่ ไม่ใช่ข้อกำหนด
ไม่มีการนำเสนอหรือสื่อนัยถึงการเปรียบเทียบกับคู่แข่ง หัวข้อเดียวคือระบบนิเวศ NextPDF และวิธีที่ส่วนต่างๆประกอบเข้าด้วยกัน
บริดจ์เฟรมเวิร์กและตัวเรนเดอร์เป็นทางเลือกที่อิสระต่อกัน บริดจ์ไม่ขยายความสามารถของเอนจิน ส่วนตัวเรนเดอร์ก็ไม่ขึ้นกับเฟรมเวิร์ก
ตัวเรนเดอร์ภายนอกเพิ่มการพึ่งพาความพร้อมใช้งาน Gotenberg และ Cloudflare เพิ่มการเรียกข้ามเครือข่ายและบริการที่ต้องดำเนินการ นั่นคือข้อแลกเปลี่ยนที่ต้องยอมรับ ไม่ใช่ต้นทุนแอบแฝง
ความสามารถที่กั้นตามระดับไม่เกี่ยวข้องกับการผสานการทำงาน คุณสมบัติเชิงพาณิชย์ปลดล็อกด้วยระดับ ไม่ใช่ด้วยบริดจ์หรือตัวเรนเดอร์ใด ดูขอบเขตด้านล่าง

แพ็กเกจในระบบนิเวศและการแบ่งระดับ — edition availability
Edition	Availability
Core	ทุกแพ็กเกจการผสานการทำงาน (บริดจ์ Artisan Gotenberg Cloudflare Connect) ทำงานกับ Core และอยู่ภายใต้ Apache-2.0 แพ็กเกจเหล่านี้ปรับเอนจินหรือเปิดให้เข้าถึง เอนจิน โดยไม่กั้นคุณสมบัติ
Pro	คุณสมบัติเชิงพาณิชย์ (การลงนามพื้นฐาน PAdES, PDF/A, บาร์โค้ดขั้นสูง) ปลดล็อกตามระดับ และจากนั้นจะใช้งานได้ ผ่าน การผสานการทำงานใด ก็ได้ ไม่ใช่ด้วยการสลับการผสานการทำงาน
Enterprise	ใบแจ้งหนี้แบบมีโครงสร้าง นโยบายการตรวจสอบความถูกต้อง และประตูยืนยัน โดยมนุษย์ของ Connect สำหรับเครื่องมือที่มีความเสี่ยงสูงเป็นความสามารถตามระดับ ซึ่งไม่ขึ้นกับการผสานการทำงานเช่นกัน

เอกสารที่เกี่ยวข้อง

ไปป์ไลน์ HTML — สิ่งที่เอนจิน CSS ภายในกระบวนการครอบคลุม เพื่อให้คุณทราบว่าเมื่อใดจำเป็นต้องใช้ตัวเรนเดอร์เบราว์เซอร์จริงๆ
เมื่อใดไม่ควรใช้ NextPDF — ขอบเขตที่ตรงไปตรงมาเกี่ยวกับปัญหาเอกสารที่เอนจินไม่ใช่เครื่องมือที่เหมาะสม
รากฐาน PHP 8.4 — พื้นฐานรันไทม์ที่ทุกแพ็กเกจใช้ร่วมกัน และสิ่งที่เส้นทาง backport รักษาไว้

อภิธานศัพท์

เอนจินหลัก — nextpdf/core เอนจิน PDF 2.0 ภายในกระบวนการที่แพ็กเกจอื่นทุกตัวต่อยอดจากเอนจินนี้
บริดจ์เฟรมเวิร์ก — แพ็กเกจการผสานการทำงาน (Laravel/Symfony/CodeIgniter) ที่ปรับเอนจินให้เข้ากับรูปแบบการใช้งานเฉพาะของเฟรมเวิร์กโดยไม่เปลี่ยนแปลงความสามารถ
แพ็กเกจตัวเรนเดอร์ — แพ็กเกจที่มอบหมายการจัดเลย์เอาต์ HTML หรือ Office ให้กับเอนจินภายนอก (Artisan/Cloudflare/Gotenberg) เมื่อเอนจินภายในกระบวนการไม่ใช่เครื่องมือที่เหมาะสม
Form XObject — ส่วนเนื้อหา PDF ที่ใช้ซ้ำได้ Artisan นำหน้าที่เรนเดอร์ด้วยเบราว์เซอร์เข้ามาเป็นส่วนเดียวเพื่อให้ข้อความยังคงเลือกได้
NextPDF Connect — nextpdf/server แพ็กเกจที่เปิดให้เข้าถึงเอนจินผ่าน MCP, REST และ gRPC พร้อมขอบเขตการดำเนินการแบบกำหนดผลได้แน่นอน
Soft dependency — โมเดลของ Connect ที่เครื่องมือจะปรากฏขึ้นโดยอัตโนมัติเมื่อแพ็กเกจ NextPDF ที่เป็นทางเลือกถูกติดตั้ง โดยไม่ต้องเปลี่ยนแปลงโค้ด