เอกสารอ้างอิง Gotenberg API

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

แพ็กเกจ Gotenberg เปิดให้ใช้บริดจ์บริการหนึ่งตัวคือ GotenbergBridge บริดจ์นี้แปลงเอกสาร Office (docx, xlsx, pptx, odt, ods, odp) เป็น Portable Document Format (PDF) โดยส่งคำขอ POST ไปยังบริการ Gotenberg ภายนอก บริดจ์ทำงานกับวัตถุค่าที่คุณส่งเข้าไปหรืออ่านออกมา ได้แก่ GotenbergConfig (ตัวระบุบริการและขีดจำกัดที่เปลี่ยนแปลงไม่ได้), OfficeFormat (enum ของรูปแบบที่รองรับ), GotenbergConvertPayload (เนื้อหาคำขอแบบ multipart) และ GotenbergConvertResult (การตอบกลับ PDF ที่แยกวิเคราะห์แล้ว) ชั้นสนับสนุนประกอบด้วย GotenbergSecurityPolicy, GotenbergResponseParser และ PinnedCurlTransport ซึ่งจัดเตรียมกลไกการตรวจสอบความถูกต้อง การแยกวิเคราะห์ และการขนส่งแบบปักหมุดที่บริดจ์เรียกใช้ภายใน ใช้ชั้นนี้เฉพาะเมื่อคุณเขียนโค้ดการขนส่งหรือโค้ดทดสอบแบบกำหนดเอง

เริ่มต้นที่นี่: สร้าง GotenbergConfig ด้วย URL ของบริการแบบ Hypertext Transfer Protocol Secure (HTTPS) จากนั้นส่งต่อไปยัง GotenbergBridge พร้อมไคลเอนต์ PSR-18 และแฟกทอรี PSR-17 ของคุณ เรียก convertFile() หรือ convertString() แล้วอ่าน pdfData จาก GotenbergConvertResult ที่ส่งกลับมา

งานที่พบบ่อย

ใช้สนิปเป็ตที่ผ่านการตรวจสอบและเรียกใช้งานได้เหล่านี้สำหรับงานในแพ็กเกจที่มักต้องทำบ่อยที่สุด

แปลงไฟล์บนดิสก์เป็น PDF

ระบุพาธให้บริดจ์ แล้วบริดจ์จะตรวจหารูปแบบจากนามสกุลไฟล์

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

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

สิ่งที่ทำ: ตรวจสอบความถูกต้องของ URL พาธ ขนาด และชื่อไฟล์ ส่งคำขอแบบ multipart หนึ่งคำขอ แล้วเขียนไบต์ PDF ที่ส่งกลับมาลงดิสก์

แปลงไบต์ในหน่วยความจำเป็น PDF

ใช้ convertString() เมื่อมีไบต์อยู่แล้ว ชื่อไฟล์จะกำหนดวิธีตรวจหารูปแบบ

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

สิ่งที่ทำ: ตรวจหา xlsx จากชื่อไฟล์ แปลงไบต์ และยืนยันว่าผลลัพธ์ขึ้นต้นด้วยลายเซ็น %PDF ก่อนนำไปใช้

ตรวจสอบความพร้อมของบริการก่อนแปลง

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

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

สิ่งที่ทำ: คืนค่า false (ไม่เคยโยนข้อยกเว้น) สำหรับ URL ที่ว่างเปล่า ไม่ใช่ HTTPS หรือเป็นที่อยู่ส่วนตัว รวมถึงข้อผิดพลาดเครือข่ายใดๆ เพื่อให้หยุดการทำงานได้อย่างรวดเร็วก่อนส่งคำขอแปลง

บริดจ์

ตารางนี้สรุปส่วนติดต่อของบริดจ์ ใช้เมื่อต้องสร้าง GotenbergBridge หรือเรียกเมธอดแปลงและเมธอดตรวจสอบความพร้อมของบริดจ์

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, ไคลเอนต์ PSR-18, แฟกทอรี PSR-17, logger เสริม, นโยบาย HTML เสริม, response factory เสริม	ใช้ `DefaultHtmlSecurityPolicy` เมื่อคุณไม่ได้กำหนดนโยบาย	`GotenbergBridge`	ข้อผิดพลาดจากการ wiring คอนเทนเนอร์	response factory เปิดใช้งานการขนส่ง cURL แบบปักหมุดเมื่อจำเป็นต้องใช้การปักหมุด
`GotenbergBridge::convertFile(string $filePath)`	พาธในระบบไฟล์ไปยังเอกสาร Office	ใช้นามสกุลไฟล์สำหรับการตรวจหารูปแบบ	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` สำหรับรูปแบบที่ไม่รองรับ	แก้พาธจริงและตรวจสอบความสามารถในการอ่าน ขนาด และชื่อไฟล์
`GotenbergBridge::convertString(string $content, string $fileName)`	ไบต์ดิบและชื่อไฟล์ต้นฉบับ	ใช้นามสกุลของชื่อไฟล์สำหรับการตรวจหารูปแบบ	`GotenbergConvertResult`	เหมือนกับ `convertFile`	ใช้เมื่อแอปพลิเคชันของคุณมีไบต์ของไฟล์อยู่แล้ว
`GotenbergBridge::isAvailable()`	ไม่มี	ส่ง HEAD ไปยัง `/health` เมื่อ config ถูกต้อง	`bool`	คืนค่า `false` เมื่อเกิดข้อผิดพลาด	เป็นสัญญาณความพร้อมเท่านั้น
`GotenbergBridge::getHtmlSecurityPolicy()`	ไม่มี	คืนนโยบายของชั้นการแยกวิเคราะห์ที่กำหนดค่าไว้	`HtmlSecurityPolicyInterface`	ไม่คาดว่าจะเกิด	ใช้เสริมกับนโยบายความปลอดภัยระดับการขนส่ง

การกำหนดค่าและเพย์โหลด

ตารางนี้ครอบคลุมวัตถุค่าที่คุณสร้างโดยตรง ได้แก่ตัวระบุบริการ GotenbergConfig และตัวพาคำขอและการตอบกลับ GotenbergConvertPayload/GotenbergConvertResult ใช้วัตถุเหล่านี้เมื่อต้องการควบคุมรายละเอียดมากกว่าที่จุดเข้าใช้งานการแปลงทั้งสองรายการให้ไว้

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API URL, timeout, ขนาดไฟล์สูงสุด, bearer token, ชุดหมุด	URL ที่ว่างเปล่าถือว่าไม่ถูกต้อง ขนาดสูงสุดเริ่มต้นคือ 50 MiB	`GotenbergConfig`	ไม่คาดว่าจะเกิด	เก็บคีย์ API ไว้เป็นความลับ
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, อาร์เรย์หมุด	ค่าทางเลือกที่ขาดหายไปจะใช้ค่าเริ่มต้นของคอนสตรัคเตอร์	`GotenbergConfig`	ไม่คาดว่าจะเกิด	รายการของสตริงจะละเว้นค่าที่ไม่ใช่สตริง
`GotenbergConfig::isValid()`	ไม่มี	ถูกต้องเมื่อ API URL ไม่ว่างเปล่า	`bool`	ไม่คาดว่าจะเกิด	ระบบจะตรวจสอบความปลอดภัยของ URL ก่อนการดำเนินการเครือข่ายใดๆ
`GotenbergConfig::allPublicKeyPins()`	ไม่มี	รวมหมุดหลักและหมุดสำรอง	`list<string>`	ไม่คาดว่าจะเกิด	รายการที่ว่างเปล่าจะปิดใช้งานการปักหมุด
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	ชื่อไฟล์, ไบต์, รูปแบบ, แฟล็กการวางแนว, ช่วงหน้า	แนวตั้งและทุกหน้า	`GotenbergConvertPayload`	ไม่คาดว่าจะเกิด	เพย์โหลดจะถูกแปลงเป็นข้อมูลฟอร์มแบบ multipart
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	ขอบเขต multipart	รวมฟิลด์ช่วงหน้าเฉพาะเมื่อฟิลด์นั้นไม่ว่างเปล่า	`string`	ไม่คาดว่าจะเกิด	บริดจ์เป็นตัวสร้างขอบเขต
`GotenbergConvertPayload::contentType(string $boundary)`	ขอบเขต multipart	ใช้ `multipart/form-data`	`string`	ไม่คาดว่าจะเกิด	แนบเป็น `Content-Type` ของคำขอ
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	ไบต์ PDF ที่แปลงแล้ว, รูปแบบต้นทาง, ระยะเวลาการเรนเดอร์เสริม	ระยะเวลาการเรนเดอร์เป็น `0.0` เมื่อไม่ได้วัด	`GotenbergConvertResult`	ไม่คาดว่าจะเกิด	ส่งกลับโดย `GotenbergResponseParser::parse()`
`GotenbergConvertResult::isValid()`	ไม่มี	ถูกต้องเมื่อไบต์ PDF ที่แปลงแล้วไม่ว่างเปล่าและมีลักษณะเป็นข้อมูล PDF	`bool`	ไม่คาดว่าจะเกิด	ตรวจสอบก่อนจัดเก็บถาวรหรือสตรีมผลลัพธ์
`GotenbergConvertResult::size()`	ไม่มี	นับไบต์ PDF ที่แปลงแล้ว	`int`	ไม่คาดว่าจะเกิด	ใช้สำหรับโควตา การวัดและส่งข้อมูล (telemetry) และขีดจำกัดการตอบกลับ

รูปแบบ Office

ตารางนี้ครอบคลุม enum OfficeFormat ใช้ enum นี้เพื่อแมปนามสกุลไฟล์กับรูปแบบ อ่านประเภท MIME สำหรับการอัปโหลด หรือตรวจสอบรูปแบบทั้งหกรายการที่รองรับ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`OfficeFormat::fromExtension(string $ext)`	นามสกุลไฟล์ที่มีหรือไม่มีจุดนำหน้า	จับคู่โดยไม่สนใจตัวพิมพ์เล็กพิมพ์ใหญ่	`OfficeFormat`	`ValueError` สำหรับนามสกุลที่ไม่รองรับ	ค่าที่รองรับ: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`
`OfficeFormat::mimeType()`	ไม่มี	แมป enum case ไปยังประเภท MIME สำหรับการอัปโหลด	`string`	ไม่คาดว่าจะเกิด	ใช้ในส่วนไฟล์แบบ multipart
`OfficeFormat::extension()`	ไม่มี	คืนค่าที่กำหนดไว้ใน enum	`string`	ไม่คาดว่าจะเกิด	มีประโยชน์ในการวินิจฉัยและชื่อไฟล์

ความปลอดภัย การแยกวิเคราะห์ และการขนส่ง

ตารางนี้ครอบคลุมกลไกภายในที่บริดจ์เรียกใช้ให้คุณ ใช้ตารางนี้เฉพาะเมื่อคุณเขียนการขนส่งแบบกำหนดเอง สร้างการเรียก Hypertext Transfer Protocol (HTTP) แบบกำหนดเองที่ยังต้องใช้การแยกวิเคราะห์ของแพ็กเกจ หรือตรวจสอบพฤติกรรมความปลอดภัยและการปักหมุดระดับล่าง

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	API base URL	แยกวิเคราะห์และตรวจสอบความถูกต้องของปลายทางก่อนการดำเนินการเครือข่ายใดๆ	`array`	`RuntimeException` สำหรับ URL ที่ไม่ปลอดภัยหรือไม่ถูกต้อง	ป้องกันไม่ให้การระบุปลายทางผิดพลาดในลักษณะ server-side request forgery (SSRF) ผ่านเข้าสู่โค้ดการแปลง
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	โฮสต์และรายการ Internet Protocol (IP) ที่ปักหมุด	ตรวจสอบว่า Domain Name System (DNS) ตรงกับหมุดที่คาดไว้	`void`	`RuntimeException` เมื่อหมุดล้าสมัยหรือไม่ถูกต้อง	ใช้ในการปรับใช้แบบปักหมุดและการวินิจฉัยเชิงปฏิบัติการ
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	ขนาดจริงและค่าสูงสุดที่กำหนดค่าไว้	ยอมรับไฟล์ที่มีขนาดเท่ากับหรือต่ำกว่าขีดจำกัดที่กำหนดค่าไว้	`void`	`RuntimeException` เมื่อไฟล์มีขนาดใหญ่เกินไป	บังคับใช้ก่อนการสร้างคำขอ
`GotenbergSecurityPolicy::validateFileName(string $name)`	ชื่อไฟล์ต้นฉบับ	ปฏิเสธรูปแบบชื่อไฟล์ที่ไม่ปลอดภัยหรือไม่รองรับ	`void`	`RuntimeException` สำหรับชื่อที่ไม่ถูกต้อง	ป้องกันชื่อไฟล์แบบ multipart ที่ผิดรูปแบบ
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	การตอบกลับ PSR-7 และรูปแบบ Office ที่คาดหวัง	ดึงไบต์ PDF ที่แปลงแล้วออกจากการตอบกลับที่สำเร็จ	`GotenbergConvertResult`	`GotenbergConvertException` สำหรับการตอบกลับที่ล้มเหลวหรือเอาต์พุต PDF ที่ไม่ถูกต้อง	ตัวแยกวิเคราะห์กลางสำหรับการแปลงไฟล์และสตริง
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	แฟกทอรี PSR-17, IP ที่ปักหมุด, คีย์สาธารณะที่ปักหมุด, timeout	ไม่มีหมุดและ timeout 30 วินาที	`PinnedCurlTransport`	ไม่คาดว่าจะเกิด	ใช้เฉพาะเมื่อจำเป็นต้องปักหมุดในระดับ cURL
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	คำขอ PSR-7	ส่งผ่าน cURL ด้วย timeout และการควบคุมการปักหมุดที่กำหนดค่าไว้	`ResponseInterface`	`GotenbergConvertException` เมื่อ cURL/การขนส่งล้มเหลว	ใช้เมื่อไม่สามารถมอบหมายการปักหมุดให้กับไคลเอนต์ HTTP อื่นได้
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	คำขอ, โฮสต์ และพอร์ต	สร้างอาร์เรย์ตัวเลือก cURL ที่ `sendRequest()` ใช้	`array`	ข้อผิดพลาดจากคำขอที่ไม่ถูกต้องหรือการกำหนดค่าหมุด	การวินิจฉัยระดับล่างและจุดเชื่อมต่อสำหรับการทดสอบ

หมายเหตุการพัฒนา

ปฏิบัติต่อ Gotenberg เป็นขอบเขตบริการภายนอกเสมอ กำหนด timeout, ขนาด, URL และนโยบายการปักหมุดอย่างตั้งใจ
convertFile() อ่านไฟล์ทั้งไฟล์เข้าสู่หน่วยความจำก่อนการสร้างคำขอ
บันทึกข้อมูลเมตา เช่น ชื่อไฟล์และความยาวเนื้อหา ไม่ใช่เนื้อหาของไฟล์