ติดตั้ง NextPDF Gotenberg

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

การติดตั้งบริดจ์มีสองส่วน ได้แก่ แพ็กเกจ PHP และดีเพนเดนซี HTTP ตาม PHP Standard Recommendation (PSR) ซึ่งติดตั้งด้วย Composer และบริการ Gotenberg ที่แพ็กเกจเรียกใช้งาน บริดจ์แปลงไฟล์โดยส่งงานไปยังบริการนี้ ดังนั้นจะยังแปลงไฟล์ไม่ได้จนกว่าจะเข้าถึงอินสแตนซ์ Gotenberg ได้

ดำเนินการทั้งสองส่วนให้เสร็จก่อนเขียนโค้ดสำหรับการแปลง

ข้อกำหนด

ข้อกำหนด	ข้อจำกัด	เหตุผล
PHP	`>=8.4 <9.0`	แพ็กเกจประกาศไว้ใน `composer.json`
NextPDF core	`^3.0`	ระบุเป็นดีเพนเดนซีโดยตรงใน `composer.json`
PSR-18 HTTP client	`^1.0`	บริดจ์ส่งคำขอผ่าน `Psr\Http\Client\ClientInterface` ที่ฉีดเข้ามา
PSR-17 HTTP factories	`^1.1`	บริดจ์สร้างคำขอและสตรีมด้วย PSR-17 factories ที่ฉีดเข้ามา
PSR-3 logger	`^3.0` (ไม่บังคับ)	สามารถฉีด logger เพื่อบันทึก debug ระดับคำขอได้
บริการ Gotenberg	เข้าถึงได้ผ่าน HTTPS	บริการภายนอกเป็นผู้ดำเนินการแปลง แพ็กเกจนี้ไม่ได้แปลงไฟล์เอง

บริดจ์ไม่ได้รวม PSR-18 client หรือ PSR-17 factories มาให้ ให้เลือกการนำไปใช้งานที่เหมาะกับแอปพลิเคชันของคุณ เช่น จับคู่ client ที่ใช้ Guzzle กับ PSR-17 factories ของมัน หรือใช้ Symfony HTTP client กับ nyholm/psr7 การนำไปใช้งานใดๆที่สอดคล้องกับสัญญา PSR ที่เกี่ยวข้องสามารถใช้งานได้ เนื่องจากบริดจ์ขึ้นอยู่กับ interface ไม่ใช่ไลบรารีเฉพาะตัวใดตัวหนึ่ง

ขั้นตอนที่ 1 — ติดตั้งแพ็กเกจ

เพิ่มแพ็กเกจด้วย Composer:

composer require nextpdf/gotenberg

Composer จะ resolve ดีเพนเดนซี nextpdf/core ^3.0 และสัญญา PSR HTTP ได้แก่ psr/http-client, psr/http-factory และ psr/log โดย ไม่ ติดตั้ง HTTP client ที่เป็นรูปธรรมตัวใดตัวหนึ่ง

ขั้นตอนที่ 2 — ติดตั้ง PSR-18 client และ PSR-17 factories

ติดตั้ง PSR-18 client หนึ่งตัวและชุด PSR-17 factories ที่เข้าคู่กันหนึ่งชุด สำหรับ Guzzle ให้ใช้:

composer require guzzlehttp/guzzle guzzlehttp/psr7

หรือสำหรับ Symfony HTTP client และ Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

ส่งการนำไปใช้งานเหล่านี้ไปยัง constructor ของบริดจ์ บริดจ์จะไม่สร้าง HTTP client เอง คุณเป็นผู้เลือกการนำไปใช้งานเมื่อประกอบบริดจ์ ดู /integrations/gotenberg/configuration/ สำหรับรูปแบบของ constructor และ /integrations/gotenberg/quickstart/ สำหรับตัวอย่างการประกอบที่สมบูรณ์

ขั้นตอนที่ 3 — จัดเตรียมบริการ Gotenberg

บริดจ์เรียกใช้ route การแปลง LibreOffice ของ Gotenberg ดังนั้นให้รันอินสแตนซ์ Gotenberg ที่บริดจ์สามารถเข้าถึงได้ โครงการต้นทางเผยแพร่ container image ไว้แล้ว สำหรับการพัฒนาบนเครื่องท้องถิ่น ให้ใช้:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

คำสั่งนี้ทำให้ Gotenberg พร้อมใช้งานที่พอร์ต 3000 ผ่าน HTTP แบบธรรมดา ใช้สำหรับการพัฒนาบนเครื่องท้องถิ่นเท่านั้น บริดจ์ กำหนดให้ต้องใช้ HTTPS สำหรับ URL ของ application programming interface (API) ที่กำหนดค่าไว้ และจะปฏิเสธ http:// แบบธรรมดาก่อนส่งคำขอใดๆ สำหรับการใช้งานทุกกรณีที่ไม่ใช่การทดลองบนเครื่องท้องถิ่น ให้วาง Gotenberg ไว้หลัง reverse proxy หรือ service mesh ที่ทำหน้าที่ terminate Transport Layer Security (TLS) จากนั้นชี้บริดจ์ไปยัง endpoint แบบ HTTPS /integrations/gotenberg/security-and-operations/ อธิบายรูปแบบการดีพลอยสำหรับ production การเปิดให้เข้าถึงผ่านเครือข่าย และการพิสูจน์ตัวตน

แท็ก image ที่แสดงไว้ที่นี่ (gotenberg/gotenberg:8) คือสายเวอร์ชันหลักของ Gotenberg ที่ README ต้นทางและเส้นฐานการผสานรวมของโครงการนี้อ้างอิงถึง ใน production ให้ตรึงไว้กับแท็ก patch ที่เจาะจง แทนการติดตามแท็กเวอร์ชันหลักที่เปลี่ยนแปลงอยู่เสมอ นอกจากนี้ ให้ตรวจสอบ route (/forms/libreoffice/convert, /health) เทียบกับเวอร์ชันของ Gotenberg ที่คุณดีพลอย บริดจ์สมมติว่ามี route สองเส้นทางนี้เท่านั้น และไม่ได้ตั้งสมมติฐานอื่นใด เกี่ยวกับบริการนี้

ขั้นตอนที่ 4 — ตรวจสอบการประกอบ

เมื่อถึงขั้นนี้ แพ็กเกจและ HTTP client ควรถูกติดตั้งแล้ว และควรเข้าถึง Gotenberg ผ่าน HTTPS ได้ ก่อนรันการแปลงจริง ให้ยืนยันว่าบริดจ์สามารถเข้าถึงบริการได้ด้วย health probe ที่มีในตัว:

<?php

declare(strict_types=1);

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

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() จะตรวจสอบ URL ที่กำหนดค่าไว้ก่อนเป็นอันดับแรก โดยจะคืนค่า false สำหรับ URL ที่ว่างเปล่า URL ที่ไม่ใช่ HTTPS หรือ URL ที่เป็นแอดเดรสส่วนตัว โดยไม่ ส่งทราฟฟิกผ่านเครือข่าย จากนั้นจะส่งคำขอ HEAD ไปยัง <apiUrl>/health และรายงานว่าบริการพร้อมใช้งานเมื่อสถานะต่ำกว่า 500 หากเกิดข้อผิดพลาดของเครือข่าย บริดจ์จะดักจับข้อผิดพลาดนั้นและรายงานว่าบริการไม่พร้อมใช้งานแทนที่จะโยน exception

หมายเหตุเกี่ยวกับเวอร์ชัน

เอกสารนี้อธิบายแพ็กเกจในสายเวอร์ชัน ^3.0 สายเวอร์ชันนี้ตรงกับข้อกำหนดใน composer.json และเมทริกซ์การสนับสนุนใน SECURITY.md ซึ่งระบุว่า 3.x ได้รับการสนับสนุนและ 2.x ไม่ได้รับการสนับสนุน การอ้างอิง 0.x ก่อนหน้านี้ในหน้าโครงร่างภายในรีโพมีอยู่ก่อนสายเวอร์ชัน 3.0 ข้อจำกัดใน composer.json มีผลเหนือกว่าการอ้างอิงเหล่านั้น

ดูเพิ่มเติม

/integrations/gotenberg/overview/ — บริดจ์ทำอะไรและแปลงไฟล์รูปแบบใดได้บ้าง
/integrations/gotenberg/configuration/ — อาร์กิวเมนต์ของ constructor และฟิลด์การกำหนดค่าทุกรายการ
/integrations/gotenberg/quickstart/ — การแปลงครั้งแรกที่สมบูรณ์และรันได้จริง
/integrations/gotenberg/security-and-operations/ — วิธีดูแลการทำงานของดีเพนเดนซี Gotenberg อย่างปลอดภัย
/integrations/gotenberg/boot-and-discovery/ — การประกอบอัตโนมัติของเฟรมเวิร์ก