การกำหนดค่า NextPDF Gotenberg

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

การกำหนดค่าประกอบด้วยสองส่วน ได้แก่ value object ที่เปลี่ยนแปลงไม่ได้ชื่อ GotenbergConfig ซึ่งอธิบายบริการและขีดจำกัดของบริการ และคอนสตรักเตอร์ GotenbergBridge ซึ่งรับ collaborator แบบ PHP Standard Recommendation (PSR) สำหรับ Hypertext Transfer Protocol (HTTP) คุณต้องจัดเตรียมทั้งสองส่วนด้วยการฉีดผ่านคอนสตรักเตอร์อย่างชัดแจ้ง แพ็กเกจนี้ไม่มีสถานะส่วนกลาง ไม่อ่านตัวแปรสภาพแวดล้อม และไม่กำหนด endpoint เริ่มต้นที่ซ่อนอยู่

ออบเจ็กต์การกำหนดค่า

GotenbergConfig เป็น value object แบบ final readonly คุณสร้างออบเจ็กต์นี้ได้โดยตรงด้วยอาร์กิวเมนต์แบบมีชื่อ หรือสร้างจากอาร์เรย์แบบ associative ด้วย GotenbergConfig::fromArray() ก็ได้

ฟิลด์

ฟิลด์	ชนิดข้อมูล	ค่าเริ่มต้น	ผลกระทบ
`apiUrl`	`string`	`''`	Uniform Resource Locator (URL) ฐานสำหรับบริการ Gotenberg ต้องระบุค่านี้ ค่าว่างจะทำให้การกำหนดค่าไม่ถูกต้องและคำขอแปลงทั้งหมดจะล้มเหลวทันที ต้องใช้ Hypertext Transfer Protocol Secure (HTTPS)
`timeout`	`int`	`30`	ระยะหมดเวลาการถ่ายโอนแบบตายตัว หน่วยเป็นวินาที ทรานสปอร์ตแบบ cURL-pinned จะนำค่านี้ไปใช้เมื่อถูกเลือก
`maxFileSize`	`int`	`52_428_800`	ขนาดอินพุตสูงสุดเป็นไบต์ (50 MiB) อินพุตที่มีขนาดใหญ่กว่านี้จะถูกปฏิเสธก่อนมีคำขอใด ๆ
`apiKey`	`string`	`''`	Bearer token เมื่อไม่ว่าง ค่านี้จะถูกส่งเป็นเฮดเดอร์ `Authorization: Bearer <token>` และถูกทำเครื่องหมายด้วย `#[\SensitiveParameter]` จึงถูกปกปิดใน stack trace
`pinnedPublicKeys`	`list<string>`	`[]`	พิน Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) หลักในรูปแบบ `sha256/<base64>` ค่าว่างจะปิดใช้การปักหมุด
`backupPublicKeys`	`list<string>`	`[]`	พิน TLS SPKI สำรอง ซึ่งแยกเก็บไว้ต่างหากเพื่อให้ตรวจสอบความถูกต้องของการหมุนเวียนได้อย่างเป็นอิสระ

การสร้างโดยตรง

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

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

การสร้างจากอาร์เรย์

fromArray() ยอมรับคีย์แบบ snake_case และจะละเว้นค่าที่มีรูปแบบไม่ถูกต้องแทนที่จะโยนข้อยกเว้น api_url ที่ไม่ใช่สตริงจะกลายเป็น '' timeout ที่ไม่ใช่ int จะถอยกลับไปใช้ 30 max_file_size ที่ไม่ใช่ int จะถอยกลับไปใช้ค่าเริ่มต้น 50 MiB รายการพินที่ไม่ใช่อาร์เรย์จะกลายเป็น [] รายการที่ไม่ใช่สตริงภายในอาร์เรย์พินจะถูกตัดทิ้ง

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

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

ความถูกต้อง

isValid() จะคืนค่า true เฉพาะเมื่อ apiUrl เป็นสตริงที่ไม่ว่างเท่านั้น เมธอดนี้ไม่ตรวจสอบเครือข่ายหรือสคีมแต่อย่างใด นโยบายความปลอดภัยจะจัดการ HTTPS และการคัดกรองที่อยู่ภายในเครือข่ายส่วนตัวขณะแปลง หากการกำหนดค่าไม่ถูกต้อง convertFile() และ convertString() จะโยน GotenbergConvertException พร้อมข้อความ Invalid Gotenberg configuration: apiUrl is empty การกำหนดค่าที่ไม่ถูกต้องยังทำให้ isAvailable() คืนค่า false โดยไม่มีการเรียกเครือข่ายใด ๆ

คอนสตรักเตอร์ของบริดจ์

GotenbergBridge รับการกำหนดค่าพร้อม collaborator แบบ PSR:

อาร์กิวเมนต์	ชนิดข้อมูล	จำเป็น	ผลกระทบ
`config`	`GotenbergConfig`	ใช่	ตัวอธิบายบริการและขีดจำกัดตามที่ระบุไว้ข้างต้น
`httpClient`	`Psr\Http\Client\ClientInterface`	ใช่	ไคลเอนต์ PSR-18 ที่ใช้สำหรับ health probe และทรานสปอร์ตสำรอง
`requestFactory`	`Psr\Http\Message\RequestFactoryInterface`	ใช่	สร้างคำขอ PSR-7
`streamFactory`	`Psr\Http\Message\StreamFactoryInterface`	ใช่	สร้างสตรีมเนื้อหาของคำขอ
`logger`	`Psr\Log\LoggerInterface\|null`	ไม่ (ค่าเริ่มต้น `null`)	เมื่อระบุไว้ จะบันทึกรายการระดับ `debug` หนึ่งรายการต่อคำขอแปลงหนึ่งครั้ง
`htmlSecurityPolicy`	`HtmlSecurityPolicyInterface\|null`	ไม่	โดยค่าเริ่มต้นจะใช้นโยบายความปลอดภัย Hypertext Markup Language (HTML) หลัก มีผลที่ชั้นการแยกวิเคราะห์ และทำงานเสริมกับนโยบายในชั้นทรานสปอร์ต
`responseFactory`	`Psr\Http\Message\ResponseFactoryInterface\|null`	ไม่ (ค่าเริ่มต้น `null`)	จำเป็นต้องมีเพื่อเปิดใช้ทรานสปอร์ตแบบ cURL-pinned หากไม่มี บริดจ์จะใช้ไคลเอนต์ PSR-18 ที่ฉีดเข้ามาเสมอ

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

การเลือกทรานสปอร์ต

บริดจ์รองรับทรานสปอร์ตสองแบบ และจะเลือกหนึ่งแบบสำหรับคำขอแปลงแต่ละครั้ง:

ทรานสปอร์ตแบบ cURL-pinned — ใช้เมื่อมีการฉีด responseFactory เข้ามา และ มีสิ่งที่ต้องปักหมุด (URL ถูกแปลงเป็นที่อยู่ Internet Protocol (IP) หนึ่งรายการขึ้นไป หรือมีการกำหนดพิน SPKI ไว้) ทรานสปอร์ตนี้จะผูกชุดที่อยู่ที่แปลงได้ด้วย CURLOPT_RESOLVE บังคับใช้การปักหมุด SPKI ด้วย CURLOPT_PINNEDPUBLICKEY เมื่อมีพิน ตรวจสอบ peer และ host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2) นำระยะหมดเวลาที่กำหนดไว้ไปใช้ และ ปิดการติดตามการเปลี่ยนเส้นทาง (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0)
ไคลเอนต์ PSR-18 ที่ฉีดเข้ามา — ใช้ในกรณีอื่นทั้งหมด รวมถึงเมื่อ URL ของ application programming interface (API) เป็นลิเทอรัล IP สาธารณะล้วน ๆ (ไม่มี Domain Name System (DNS) ให้ปักหมุด) และไม่มีการกำหนดพิน SPKI ไว้ หรือเมื่อไม่ได้ระบุ responseFactory ไว้

สำหรับการเชื่อมต่อที่ต้านทาน DNS-rebinding และการปักหมุด TLS ให้ฉีด responseFactory และกำหนดพิน ส่วน health probe จะใช้ไคลเอนต์ PSR-18 ที่ฉีดเข้ามาเสมอ ไม่ว่าจะเลือกทรานสปอร์ตแบบใด

การปักหมุดคีย์สาธารณะ TLS

การปักหมุดใช้โมเดลลายนิ้วมือ SPKI แบบ Secure Hash Algorithm 256-bit (SHA-256) พินแต่ละรายการเป็นสตริงในรูปแบบ sha256/<base64-encoded-spki-hash> ทรานสปอร์ตยังยอมรับรูปแบบ sha256//<base64> แบบ cURL-native ด้วย และจะแปลงรูปแบบสแลชเดี่ยวให้เป็นรูปแบบนี้ คำนำหน้าอื่นใดจะทำให้เกิด InvalidSpkiPinException

allPublicKeyPins() จะคืนค่าชุดรวมที่ขจัดรายการซ้ำของ pinnedPublicKeys และ backupPublicKeys ชั้น TLS จะยอมรับใบรับรองที่มีค่าแฮช SPKI ตรงกับสมาชิก ใด ๆ ในชุดรวมนั้น สำหรับการปฏิบัติงาน ให้กำหนดพินสำรองอย่างน้อยหนึ่งรายการ เพื่อให้การหมุนเวียนใบรับรองหรือคีย์ตามแผนไม่ทำให้บริดจ์ถูกปิดกั้นจากบริการระหว่างที่คีย์ใหม่กำลังแพร่กระจาย การแยกเก็บรายการสำรองไว้ต่างหากจากรายการหลักช่วยให้คุณตรวจสอบและหมุนเวียนพินสำรองได้อย่างเป็นอิสระจากพินที่ใช้งานอยู่ ดู /integrations/gotenberg/security-and-operations/ สำหรับขั้นตอนการหมุนเวียน

ตัวเลือกการแปลงต่อคำขอ

ชนิด payload แบบ multipart (GotenbergConvertPayload) จะส่งไฟล์พร้อมตัวเลือกการแปลงของ Gotenberg แบบไม่บังคับสองตัวเลือก:

landscape (bool, ค่าเริ่มต้น false) — ส่งเป็นฟอร์มฟิลด์ landscape ด้วยค่า "true" หรือ "false" ค่าใดค่าหนึ่ง
nativePageRanges (string, ค่าเริ่มต้น '') — ส่งเป็นฟอร์มฟิลด์ nativePageRanges เฉพาะเมื่อไม่ว่าง รองรับไวยากรณ์ช่วงของ Gotenberg เช่น 1-3 หรือ 1,3,5-9 เป็นต้น

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

ดูเพิ่มเติม

/integrations/gotenberg/install/ — การติดตั้งและพื้นฐานเริ่มต้นของ Gotenberg
/integrations/gotenberg/quickstart/ — ตัวอย่างแบบครบวงจรที่รันได้
/integrations/gotenberg/production-usage/ — การจัดหาแหล่งการกำหนดค่า ความลับ ระยะหมดเวลา และการลองใหม่
/integrations/gotenberg/security-and-operations/ — โมเดลความปลอดภัยฉบับเต็มและการหมุนเวียนพิน
/integrations/gotenberg/troubleshooting/ — ความหมายของข้อยกเว้นที่เกี่ยวข้องกับการกำหนดค่า