การผสานการทำงานกับ NextPDF Gotenberg

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

หน้านี้อธิบายวิธีเชื่อมต่อบริดจ์กับส่วนอื่นของแอปพลิเคชันของคุณ ตั้งแต่การติดตั้ง การเชื่อมต่อ ไปจนถึงการส่งไฟล์ Portable Document Format (PDF) ที่แปลงแล้วเข้าสู่ไปป์ไลน์การประมวลผลภายหลังของ NextPDF บริดจ์จะแปลงเอกสาร Office เป็น PDF ส่วนไปป์ไลน์จะดูแลงานทั้งหมดหลังการแปลง สำหรับแนวคิดการออกแบบเบื้องหลังการเชื่อมต่อนี้ ดูที่ /integrations/gotenberg/boot-and-discovery/

การติดตั้ง

composer require nextpdf/gotenberg

เมื่อติดตั้งแพ็กเกจนี้ จะติดตั้ง nextpdf/core ^3.0 และสัญญา PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP) มาด้วย ให้ติดตั้งไคลเอ็นต์ PSR-18 และแฟกทอรี PSR-17 เป็นแพ็กเกจแยกต่างหาก บริดจ์พึ่งพาเฉพาะอินเทอร์เฟซ คุณจึงเลือกไลบรารีสำหรับใช้งานจริงได้เอง สำหรับขั้นตอนการติดตั้งทั้งหมด รวมถึงวิธีเรียกใช้บริการ Gotenberg ผ่าน Hypertext Transfer Protocol Secure (HTTPS) ดูที่ /integrations/gotenberg/install/

การเชื่อมต่อ

สร้างบริดจ์ด้วยอ็อบเจกต์การกำหนดค่าและคอลแลบอเรเตอร์ PSR พร้อมทั้ง inject response factory ด้วย เพื่อเปิดใช้งานทรานสปอร์ตแบบ Domain Name System (DNS)-pinning และ Transport Layer Security (TLS)-pinning:

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

บริดจ์กำหนดให้ URL ที่ตั้งค่าไว้ต้องใช้ HTTPS และจะปฏิเสธ http:// แบบธรรมดาก่อนส่งคำขอใดๆ ให้เรียกใช้ Gotenberg หลัง TLS termination แล้วชี้บริดจ์ไปยังเอ็นด์พอยต์ HTTPS

การ binding ใน container

ลงทะเบียนสามรายการใน host container ของคุณ ได้แก่ GotenbergConfig ที่สร้างจากแหล่งการกำหนดค่าของคุณ ไคลเอ็นต์ PSR-18 พร้อมแฟกทอรี PSR-17 ของคุณ และ GotenbergBridge ที่ประกอบขึ้นจากดีเพนเดนซีเหล่านั้น แพ็กเกจนี้ไม่ได้มาพร้อม binding ของตัวเอง การลงทะเบียนแบบเนทีฟของเฟรมเวิร์กเป็นหน้าที่ของแพ็กเกจผสานการทำงานเฉพาะเฟรมเวิร์ก ดูที่ /integrations/gotenberg/boot-and-discovery/

การกำหนดค่า

ฟิลด์สำหรับ service descriptor และข้อจำกัดทั้งหมดอยู่ใน GotenbergConfig ฟิลด์เหล่านี้ครอบคลุม application programming interface (API) URL, ค่า timeout, ขีดจำกัดขนาด bearer token และ TLS pin ส่วนตัวเลือกเฉพาะคำขอ เช่น landscape และ nativePageRanges จะอยู่บนชนิด payload แทน /integrations/gotenberg/configuration/ อธิบายทุกฟิลด์ พร้อมชนิด ค่าเริ่มต้น และผลของแต่ละฟิลด์

การเชื่อม PDF ที่แปลงแล้วเข้ากับไปป์ไลน์ของ NextPDF

โดยทั่วไป ขั้นตอนแบบ end-to-end มีดังนี้:

1. แปลงเอกสาร Office ด้วย convertFile() หรือ convertString()
2. นำ $result->pdfData ซึ่งบรรจุ raw PDF bytes มาโหลดเข้าสู่เอกสาร NextPDF
3. ใช้การประมวลผลภายหลัง เช่น การประกอบหน้า การใส่ลายน้ำ การแปลงเป็น PDF/A หรือการลงลายเซ็นดิจิทัล

ขั้นตอนที่ 3 เป็นหน้าที่ของ NextPDF ไม่ใช่ของบริดจ์ แพ็กเกจ nextpdf/premium ให้บริการการลงนาม โปรไฟล์ PDF/A และการใส่ลายน้ำ ให้แยกการแปลงออกจากการประมวลผลภายหลังเป็นคนละขั้นตอน เพื่อให้วินิจฉัยความล้มเหลวของแต่ละจุดได้แยกกัน

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

การรองรับ PDF Advanced Electronic Signatures (PAdES) ในรุ่น Pro รองรับเฉพาะ baseline B-B เท่านั้น ไม่รองรับ B-T, B-LT หรือ B-LTA การแปลงเอกสารผ่านบริดจ์นี้ไม่ได้หมายความว่ารองรับ timestamp หรือ long-term-validation แต่อย่างใด

การทดสอบเบื้องต้น

หลังจากเชื่อมต่อแล้ว ให้ยืนยันการผสานการทำงานโดยไม่ต้องแปลงเอกสารจริง:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() จะตรวจสอบความถูกต้องของ URL โดยไม่สร้างทราฟฟิกเครือข่าย จากนั้นส่งคำขอ HEAD ไปยัง <apiUrl>/health หลังจากนั้น ให้แปลงเอกสารขนาดเล็กหนึ่งเอกสารที่ทราบว่าใช้งานได้ ขั้นตอนนี้จะทดสอบเส้นทาง multipart แบบครบถ้วนไปยัง <apiUrl>/forms/libreoffice/convert และตรวจสอบความถูกต้องของการตอบสนอง

จุดเข้าใช้งาน Public API

ส่วนต่อประสานสาธารณะที่การผสานการทำงานนี้ใช้มีดังนี้:

• GotenbergConfig — service descriptor และข้อจำกัดแบบเปลี่ยนแปลงไม่ได้ fromArray() สร้างอ็อบเจกต์นี้จากอาร์เรย์การกำหนดค่า
• GotenbergBridge::convertFile(string $path) — แปลงไฟล์บนดิสก์
• GotenbergBridge::convertString(string $bytes, string $fileName) — แปลงไบต์ในหน่วยความจำ
• GotenbergBridge::isAvailable() — การตรวจสอบความพร้อมแบบไม่โยนข้อยกเว้น
• GotenbergConvertResult — เก็บ pdfData, sourceFormat, isValid() และ size()
• GotenbergConvertException — ชนิดข้อยกเว้นของชั้นการแปลง

สัญญาฉบับสมบูรณ์อยู่ใน /integrations/gotenberg/configuration/ และ /integrations/gotenberg/troubleshooting/ ซึ่งครอบคลุมการเลือกทรานสปอร์ตและแคตตาล็อกข้อยกเว้น

ดูเพิ่มเติม

• /integrations/gotenberg/boot-and-discovery/ — เหตุผลของรูปแบบการเชื่อมต่อนี้
• /integrations/gotenberg/quickstart/ — การแปลงครั้งแรกแบบมีคำแนะนำ
• /integrations/gotenberg/production-usage/ — secret, การลองใหม่, timeout, observability
• /integrations/gotenberg/install/ — การติดตั้งแพ็กเกจและบริการ Gotenberg