เริ่มต้นใช้งาน NextPDF Gotenberg แบบรวดเร็ว

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

บทแนะนำนี้แสดงวิธีแปลงไฟล์ .docx หนึ่งไฟล์เป็น Portable Document Format (PDF) เมื่อทำเสร็จแล้ว คุณจะได้สามสิ่ง ได้แก่ อินสแตนซ์ bridge ที่ใช้งานได้ การเชื่อมต่อกับบริการที่ตรวจสอบแล้ว และไฟล์ PDF บนดิสก์ โปรแกรมฉบับเต็มอยู่ในรีโพซิทอรีที่ examples/convert-office-to-pdf.php และโค้ดตัวอย่างด้านล่างมาจากโปรแกรมดังกล่าว

บทแนะนำนี้เริ่มจากแนวทางที่เรียบง่ายที่สุดซึ่งใช้งานได้จริง หัวข้อสำหรับการใช้งานจริง เช่น การจัดเตรียม secret การลองใหม่ การหมดเวลา และการสังเกตการณ์ระบบ อธิบายไว้ใน /integrations/gotenberg/production-usage/

ก่อนเริ่มต้น

ก่อนดำเนินการต่อ โปรดยืนยันสามสิ่งต่อไปนี้:

1. คุณได้รัน composer require nextpdf/gotenberg แล้ว และติดตั้ง PHP Standards Recommendation (PSR)-18 client พร้อมกับ PSR-17 factories ไว้แล้ว โปรดดู /integrations/gotenberg/install/
2. บริการ Gotenberg ต้องเข้าถึงได้ผ่าน Hypertext Transfer Protocol Secure (HTTPS) bridge จะปฏิเสธ http:// แบบธรรมดาก่อนที่คำขอใดๆ จะออกจากโปรเซส
3. คุณมีไฟล์ตัวอย่างในรูปแบบใดรูปแบบหนึ่งต่อไปนี้: .docx, .xlsx, .pptx, .odt, .ods หรือ .odp นามสกุลไฟล์อื่นๆ จะล้มเหลวพร้อมกับ ValueError

ขั้นตอนที่ 1 — กำหนดบริการ

GotenbergConfig เป็น value object ที่เปลี่ยนค่าไม่ได้ อย่างน้อยต้องระบุ base URL แบบ HTTPS สำหรับบริการ Gotenberg ของคุณ:

use NextPDF\Gotenberg\GotenbergConfig;

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

transport แบบปักหมุดด้วย cURL จะใช้ timeout เป็นระยะหมดเวลาของการถ่ายโอน หน่วยเป็นวินาที เมื่อ apiKey มีค่า bridge จะส่งค่านี้ในรูปแบบ Authorization: Bearer <token> หากการติดตั้ง Gotenberg ของคุณไม่จำเป็นต้องใช้โทเค็น ให้ปล่อย apiKey ว่างไว้

ขั้นตอนที่ 2 — เชื่อมต่อ bridge

ส่ง config และคอมโพเนนต์ PSR ให้ bridge และ inject responseFactory เพื่อเปิดใช้ transport แบบ cURL พร้อมการปักหมุด Domain Name System (DNS) และ Transport Layer Security (TLS):

use NextPDF\Gotenberg\GotenbergBridge;

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

bridge จะไม่สร้าง Hypertext Transfer Protocol (HTTP) client ให้โดยอัตโนมัติ โปรดใช้ PSR-18 client และ PSR-17 factories ที่คุณติดตั้งไว้ ไฟล์ตัวอย่างแสดงการเชื่อมต่อ Guzzle ไว้ในคอมเมนต์

ขั้นตอนที่ 3 — ตรวจสอบความพร้อมใช้งาน

ก่อนแปลงไฟล์ ให้ตรวจสอบบริการก่อน ขั้นตอนนี้จะยืนยันความถูกต้องของ URL โดยยังไม่มีการรับส่งข้อมูลผ่านเครือข่าย จากนั้นจึงส่งคำขอ HEAD ไปยัง <apiUrl>/health:

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

เมื่อ URL ว่าง ไม่ใช่ HTTPS หรือเป็นที่อยู่ส่วนตัว รวมถึงเมื่อเกิดข้อผิดพลาดของเครือข่ายใดๆ isAvailable() จะคืนค่า false (ไม่มีการ throw) สถานะต่ำกว่า 500 จาก /health หมายความว่าบริการพร้อมใช้งาน

ขั้นตอนที่ 4 — แปลง

เรียก convertFile() โดยส่งพาธบนดิสก์ bridge จะทำให้พาธอยู่ในรูปแบบมาตรฐานเพื่อป้องกันการ traversal จากนั้นจะจับคู่นามสกุลไฟล์กับรูปแบบที่รองรับ ตรวจสอบขนาดและชื่อไฟล์ แล้วส่งคำขอแบบ multipart ไปยัง <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

หากต้องการแปลงไบต์ที่อยู่ในหน่วยความจำอยู่แล้ว ให้ใช้ convertString() และส่งชื่อไฟล์ต้นฉบับไปด้วย เพื่อให้ bridge สามารถตรวจหานามสกุลไฟล์ได้:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

ขั้นตอนที่ 5 — ใช้ผลลัพธ์

ผลลัพธ์มีสามส่วน ได้แก่ ไบต์ของ PDF รูปแบบต้นฉบับ และการตรวจสอบความถูกต้อง:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() จะให้ค่าจริงเมื่อ body ไม่ว่างและขึ้นต้นด้วย %PDF size() จะคืนค่าความยาวเป็นไบต์ จากจุดนี้ PDF จะเป็นสตรีมทั่วไปที่คุณสามารถส่งต่อไปยัง NextPDF เพื่อประมวลผลภายหลังได้

โปรแกรมฉบับสมบูรณ์

โปรแกรมฉบับเต็มที่รันได้จริงอยู่ที่ examples/convert-office-to-pdf.php ในรีโพซิทอรีของแพ็กเกจ โปรแกรมนี้ครอบคลุมการแยกวิเคราะห์อาร์กิวเมนต์ การกำหนดค่าตามตัวแปรสภาพแวดล้อม การตรวจสอบสถานะ การจัดการข้อผิดพลาดอย่างครบถ้วน และขั้นตอนการเขียนไฟล์ ให้รันด้วยคำสั่ง:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

ขั้นตอนต่อไป

• /integrations/gotenberg/configuration/ — ทบทวนตัวเลือกทั้งหมดและกฎการเลือก transport
• /integrations/gotenberg/production-usage/ — จัดการ secret การลองใหม่ การหมดเวลา การบันทึกล็อก และการทำงานพร้อมกัน
• /integrations/gotenberg/troubleshooting/ — ทำความเข้าใจ exception ทั้งหมดที่โค้ดนี้สามารถ throw ได้และความหมายของแต่ละรายการ
• /integrations/gotenberg/integration/ — ใช้บริการนี้ขับเคลื่อนไปป์ไลน์การเรนเดอร์ของ NextPDF