การบูตและการค้นพบของ NextPDF Cloudflare

โดยสรุป

บริดจ์นี้ไม่มี service provider, bundle หรือ hook สำหรับการค้นพบอัตโนมัติของตัวเอง บริดจ์นี้ประกอบด้วยคลาส final หลายคลาสที่มีคอนสตรักเตอร์ระบุไว้อย่างชัดเจน ในที่นี้ “discovery” หมายถึงการเลือก collaborator ที่จะ inject และ bind เข้า container ของเฟรมเวิร์กที่ใช้งาน หน้านี้อธิบายการเชื่อมต่อนั้น และไม่ได้สร้างกลไกการลงทะเบียนที่ไม่มีอยู่ในแพ็กเกจขึ้นมาเอง

วิธีค้นพบบริดจ์ตัวเรนเดอร์

ให้สร้าง CloudflareHtmlRenderer โดยตรง ไม่ได้ค้นพบขึ้นมา dependency ของตัวเรนเดอร์นี้เป็น contract แบบ PHP Standard Recommendation (PSR) ได้แก่ PSR-18, PSR-17 และ PSR-3 รวมถึงชนิด config และ contract ของแพ็กเกจเอง เฟรมเวิร์กใดก็ตามที่สามารถสร้าง collaborator เหล่านั้นได้ ก็สามารถสร้างตัวเรนเดอร์ได้ แพ็กเกจขึ้นอยู่กับ contract แบบ PSR เท่านั้น การทดสอบ tests/Unit/Architecture/PsrConformanceTest.php ยืนยันว่าไม่มี client แบบ concrete ตัวใดถูกผูกติดกับตัวเรนเดอร์ แอปพลิเคชันโฮสต์สามารถนำ binding ของ HTTP client ที่มีอยู่กลับมาใช้ซ้ำได้โดยไม่ต้องเปลี่ยนแปลง อะแดปเตอร์ NextPDF สำหรับ Laravel, Symfony และ CodeIgniter นำ binding ของ PSR-18 เดียวกันนั้นกลับมาใช้ซ้ำ แพ็กเกจนี้ไม่ได้เพิ่มแพ็กเกจเฟรมเวิร์กของตัวเอง

ลำดับการบูต

ให้ resolve collaborator ตามลำดับนี้ เพื่อให้สอดคล้องกับคอนสตรักเตอร์ของ CloudflareHtmlRenderer:

1. resolve ClientInterface ของ PSR-18 จาก binding ของ HTTP client ที่แอปพลิเคชันมีอยู่
2. resolve RequestFactoryInterface และ StreamFactoryInterface ของ PSR-17 และ resolve ResponseFactoryInterface ด้วยเมื่อคุณต้องการใช้ transport cURL ที่ถูกตรึงไว้
3. สร้าง CloudflareRendererConfig จากการกำหนดค่าที่ resolve แล้ว (ดู “ลำดับการ resolve การกำหนดค่า”)
4. หากต้องการ ให้ resolve LoggerInterface ของ PSR-3, LocalRendererFactoryInterface และ HtmlSecurityPolicyInterface ที่ระบุอย่างชัดเจน
5. สร้าง CloudflareHtmlRenderer ด้วย collaborator เหล่านั้น

ไม่มีขั้นตอนใดในลำดับนี้ติดต่อกับเครือข่าย การติดต่อกับเครือข่ายครั้งแรกเกิดขึ้นเมื่อเรียกใช้ render() หรือ isAvailable()

การ bind ใน container

ตัวอย่างการ bind ทั่วไป (pseudocode ที่ไม่ผูกกับเฟรมเวิร์กใด):

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Log\LoggerInterface;

$container->singleton(CloudflareHtmlRenderer::class, function ($c) {
    return new CloudflareHtmlRenderer(
        config:          CloudflareRendererConfig::fromArray($c->get('config')['cloudflare']),
        httpClient:      $c->get(ClientInterface::class),
        requestFactory:  $c->get(RequestFactoryInterface::class),
        streamFactory:   $c->get(StreamFactoryInterface::class),
        logger:          $c->get(LoggerInterface::class),
        responseFactory: $c->get(ResponseFactoryInterface::class),
    );
});

ลำดับการ resolve การกำหนดค่า

แพ็กเกจไม่ได้อ่าน environment variable ด้วยตนเอง แต่รับ CloudflareRendererConfig ที่สร้างเสร็จสมบูรณ์แล้ว ในแอปพลิเคชันโฮสต์ ให้ resolve การกำหนดค่าตามลำดับนี้: environment variable ก่อน จากนั้นเป็น config ที่เผยแพร่ไว้หรือ config ของเฟรมเวิร์ก แล้วจึงใช้ค่าเริ่มต้นของแพ็กเกจที่ฝังอยู่ในคอนสตรักเตอร์ (มีบันทึกไว้ใน /integrations/cloudflare/configuration/) CloudflareRendererConfig::fromArray() จะใช้ค่าเริ่มต้นจากคอนสตรักเตอร์กับคีย์ใดก็ตามที่ขาดหายไปหรือมีชนิดไม่ถูกต้อง ดังนั้น config array ที่มีเพียงบางส่วนจึงถอยกลับไปใช้ค่าเริ่มต้นได้อย่างคาดเดาได้แทนที่จะล้มเหลว

การวินิจฉัย

CloudflareRendererConfig::isValid() คือสัญญาณในช่วงบูต โดยตรวจสอบเพียงว่า workerUrl และ apiToken ไม่ว่างเปล่า และไม่มีการเรียกเครือข่าย จึงใช้เป็น deploy gate ได้ สัญญาณในช่วงรันไทม์คือ CloudflareHtmlRenderer::isAvailable() ซึ่งส่ง HTTP HEAD พร้อมการยืนยันตัวตน โดยคืนค่า true สำหรับสถานะที่ต่ำกว่า 500 และคืนค่า false (ไม่เคยโยน exception) ในกรณีอื่น จึงใช้เป็น readiness probe ได้ probe ที่ผ่านเป็นเพียงข้อบ่งชี้ ไม่ใช่การรับประกัน: POST ที่ตามมายังคงล้มเหลวได้

ดูเพิ่มเติม

• /integrations/cloudflare/integration/ — คู่มือการผสานรวมแบบครบถ้วน
• /integrations/cloudflare/overview/ — บริดจ์คืออะไรและข้ามขอบเขตใด
• /integrations/cloudflare/configuration/ — ทุกฟิลด์และค่าเริ่มต้น
• /integrations/cloudflare/security-and-operations/ — เมื่อใด transport ที่ถูกตรึงไว้จึงเริ่มทำงาน