คู่มือสำหรับนักพัฒนา Gotenberg

ภาพรวม

แพ็กเกจ Gotenberg ส่งงานแปลงเอกสารเป็น Portable Document Format (PDF) ไปยังบริการภายนอก ในโค้ดของแอปพลิเคชัน ให้กำหนดขอบเขตของบริการให้ชัดเจน ได้แก่ ตรวจสอบความถูกต้องของอินพุต สร้าง payload ส่งคำขอ แยกวิเคราะห์ผลลัพธ์ และจัดการความล้มเหลวของบริการ

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

ขอบเขตของสถาปัตยกรรม

เลเยอร์	เป็นเจ้าของโดย	ความรับผิดชอบ	อย่าใส่ไว้ที่นี่
แหล่งที่มาของการอัปโหลดหรือเอกสาร	แอปพลิเคชัน	ตรวจสิทธิ์ผู้เรียก ตรวจสอบความถูกต้องของแหล่งที่มา และเลือกนโยบายการแปลง	การตัดสินใจเรื่องจุดปลายทางของบริการหรือการตรึงการขนส่ง
การตรวจหารูปแบบ	`nextpdf/gotenberg`	จับคู่นามสกุลที่ปลอดภัยกับ `OfficeFormat`	เชื่อถือชนิดสื่อที่ประกาศมาโดยไม่ตรวจสอบความถูกต้องในระดับแอปพลิเคชัน
Bridge	`nextpdf/gotenberg`	สร้างคำขอแบบ multipart เรียก Gotenberg และแยกวิเคราะห์การตอบกลับ PDF	การคิวรีโดเมนหรือนโยบายการจัดเก็บ
บริการ Gotenberg	การปรับใช้	แปลงเอกสารสำนักงานเป็น PDF	การให้สิทธิ์ในแอปพลิเคชัน Hypertext Preprocessor (PHP)
เอนจินหลัก	`nextpdf/nextpdf`	นำเข้าหรือรวมข้อมูล PDF ที่แปลงแล้วเมื่อจำเป็น	การแปลงเอกสารสำนักงาน

วงจรชีวิตขณะรันไทม์

ขั้นตอน	พฤติกรรม	การดำเนินการของนักพัฒนา
การสร้างการกำหนดค่า	โหลดจุดปลายทางของ application programming interface (API) ค่าหมดเวลา ขนาดสูงสุด คีย์ API และพินจากการกำหนดค่า	เก็บจุดปลายทางของบริการและโทเค็นไว้นอกซอร์สโค้ด
การตรวจสอบความถูกต้องของอินพุต	ตรวจสอบเส้นทางไฟล์ ขนาดไฟล์ ชื่อไฟล์ นามสกุล และความปลอดภัยของ Uniform Resource Locator (URL)	ปฏิเสธอินพุตที่ไม่รองรับก่อนส่งออกไป
การสร้าง payload	`GotenbergConvertPayload` สร้างข้อมูลฟอร์มแบบ multipart	เก็บชื่อไฟล์เดิมไว้เฉพาะเมื่อปลอดภัยเท่านั้น
คำขอบริการ	Bridge ส่งคำขอไปยัง `/forms/libreoffice/convert`	กำหนดค่าหมดเวลาและนโยบายการขนส่ง
การแยกวิเคราะห์ผลลัพธ์	`GotenbergResponseParser::parse()` ส่งคืนไบต์ PDF และข้อมูลเมตา	ถือว่าการตอบกลับที่ไม่ใช่ PDF และการตอบกลับที่เป็นข้อผิดพลาดเป็นความล้มเหลวของการแปลง

โครงสร้างแอปพลิเคชันที่แนะนำ

เส้นทาง	วัตถุประสงค์
`app/Pdf/Conversion/*`	ตัวห่อหุ้มระดับแอปพลิเคชันสำหรับ `GotenbergBridge`
`app/Pdf/Uploads/*`	การตรวจสอบความถูกต้องของการอัปโหลด การจัดเก็บ และนโยบายชื่อไฟล์
`app/Pdf/ConversionPolicy/*`	นโยบายขนาด รูปแบบ และการเลือกบริการ
`tests/Pdf/Conversion/*`	การทดสอบรูปแบบ ไฟล์ บริการ และการขนส่ง

แยกการตรวจสอบความถูกต้องของไฟล์ออกจากการแปลง บริการแปลงควรรับเฉพาะอินพุตที่ได้รับอนุญาตแล้ว และยังคงพึ่งพาการตรวจสอบความถูกต้องของแพ็กเกจเป็นการป้องกันเชิงลึก

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

รูปแบบการแปลง

รูปแบบ	API	ใช้เมื่อ	ข้อจำกัด
แปลงจากเส้นทางไฟล์	`GotenbergBridge::convertFile()`	เอกสารถูกจัดเก็บไว้บนดิสก์แล้ว	เส้นทางต้องอ่านได้และได้รับอนุมัติตามนโยบาย
แปลงไบต์ในหน่วยความจำ	`GotenbergBridge::convertString()`	แอปพลิเคชันมีไบต์จากการอัปโหลดหรือ object store อยู่แล้ว	ชื่อไฟล์ยังเป็นตัวกำหนดการตรวจหารูปแบบ
สร้าง payload โดยตรง	`GotenbergConvertPayload`	ต้องการไบต์แบบ multipart สำหรับการทดสอบหรือโค้ดการขนส่งแบบกำหนดเอง	อย่าให้การสร้างขอบเขต (boundary) มาจากอินพุตของผู้ใช้
แยกวิเคราะห์การตอบกลับโดยตรง	`GotenbergResponseParser::parse()`	การเรียก Hypertext Transfer Protocol (HTTP) แบบกำหนดเองยังต้องใช้ตัวแยกวิเคราะห์ของแพ็กเกจ	ต้องส่ง `OfficeFormat` ที่คาดหวัง

สถานะและความพร้อม

GotenbergBridge::isAvailable() เป็นสัญญาณความพร้อม ไม่ใช่กลไกป้องกันเพียงอย่างเดียวขณะรันไทม์ บริการอาจผ่านการตรวจสอบความพร้อมแล้ว แต่ยังล้มเหลวในการแปลงครั้งถัดไป

การตรวจสอบ	วัตถุประสงค์	หมายเหตุการดำเนินงาน
ความถูกต้องของการกำหนดค่า	ตรวจหาจุดปลายทาง API ที่ขาดหายไป	เรียกใช้ระหว่างบูตแอปหรือระหว่างตรวจสอบการปรับใช้
ความพร้อมใช้งานของ `/health`	ตรวจว่าบริการเข้าถึงได้หรือไม่	ใช้สำหรับแดชบอร์ดความพร้อม
การแปลงฟิกซ์เจอร์ขนาดเล็ก	ตรวจหาพฤติกรรม LibreOffice ที่เสียหายหรือการถดถอยของบริการ	เรียกใช้ในการทดสอบ smoke ตามกำหนดเวลา ไม่ใช่ในทุกคำขอ
การตรวจสอบการหมดเวลา	ตรวจหาพฤติกรรมของบริการที่ช้า	ติดตามตามรูปแบบและขนาดไฟล์

จุดขยาย

จุดขยาย	ใช้สำหรับ	ข้อจำกัด
มาตรฐาน PHP Standard Recommendation (PSR)-18 `ClientInterface`	พฤติกรรมไคลเอนต์ HTTP แบบกำหนดเอง	ต้องสอดคล้องกับความหมายของการตอบกลับและข้อยกเว้นตาม PSR-18
แฟกทอรี PSR-17	การสร้างคำขอและสตรีม	จำเป็นสำหรับการสร้าง bridge
`HtmlSecurityPolicyInterface`	นโยบายระดับการแยกวิเคราะห์สำหรับอินพุต Hypertext Markup Language (HTML)	เสริมนโยบายความปลอดภัยของ Gotenberg
`ResponseFactoryInterface`	การสร้างการตอบกลับสำหรับการขนส่ง cURL ที่ตรึงไว้	จำเป็นเฉพาะเมื่อใช้เส้นทางการขนส่งของแพ็กเกจ
`GotenbergSecurityPolicy`	การตรวจสอบความถูกต้องของ URL ขนาดไฟล์ ชื่อไฟล์ และพิน	เก็บการให้สิทธิ์ของแอปพลิเคชันไว้นอกเลเยอร์นี้

เวิร์กโฟลว์การพัฒนา

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

การจัดการความล้มเหลว

ความล้มเหลว	ตำแหน่งที่ควรจัดการ	การตอบสนองที่แนะนำ
นามสกุลที่ไม่รองรับ	การตรวจหารูปแบบ	ปฏิเสธก่อนส่งไปยังบริการ
ชื่อไฟล์ที่ไม่ปลอดภัย	นโยบายความปลอดภัย	ปฏิเสธและปรับนโยบายการตั้งชื่อไฟล์อัปโหลดให้เป็นมาตรฐาน
ไฟล์ขนาดเกินกำหนด	นโยบายการอัปโหลดและการตรวจสอบความถูกต้องของแพ็กเกจ	ปฏิเสธก่อนอ่านหรือส่ง payload ขนาดใหญ่
Gotenberg ไม่พร้อมใช้งาน	ขอบเขตของ bridge	คืนข้อผิดพลาดของแอปพลิเคชันที่สามารถลองใหม่ได้เมื่อเหมาะสม
การตอบกลับที่ไม่ใช่ PDF	ตัวแยกวิเคราะห์การตอบกลับ	ถือเป็นความล้มเหลวของการแปลงและเก็บสถานะบริการไว้
ความล้มเหลวในการตรวจสอบความถูกต้องของพินหรือ URL	นโยบายการขนส่ง	ล้มเหลวแบบปิด (fail closed) และแจ้งเตือนผู้ปฏิบัติงาน

ค่าเริ่มต้นที่ปลอดภัย

ประเด็นที่เกี่ยวข้อง	ค่าเริ่มต้น	เมื่อใดควรแทนที่
ค่าหมดเวลา	`30` วินาที	เพิ่มหลังจากวัดความหน่วงจริงของบริการแล้วเท่านั้น
ขนาดไฟล์สูงสุด	`52,428,800` ไบต์	ลดสำหรับจุดปลายทางสาธารณะหรือแบบหลายผู้เช่า
คีย์ API	ว่างเปล่า	ตั้งค่าสำหรับการปรับใช้ Gotenberg แบบส่วนตัว
รูปแบบที่รองรับ	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`	เพิ่มรูปแบบเมื่อ `OfficeFormat` และตัวแยกวิเคราะห์รองรับเท่านั้น
ชุดพิน	ว่างเปล่า	เพิ่มพินพร้อมพินสำรองและขั้นตอนหมุนเวียน

รายการตรวจสอบการทดสอบ

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