Khởi động và khám phá NextPDF Cloudflare

Tổng quan nhanh

Cầu nối không đi kèm service provider, bundle hay hook tự động khám phá riêng. Nó là một tập hợp các lớp final với các hàm khởi tạo tường minh. Trong ngữ cảnh này, “khám phá” nghĩa là chọn các thành phần cộng tác để tiêm vào và đăng ký chúng trong container của framework của bạn. Trang này mô tả cách đấu nối đó. Nó không dựng lên một cơ chế đăng ký mà gói này vốn không có.

Cách cầu nối kết xuất được khám phá

Bạn khởi tạo CloudflareHtmlRenderer; bạn không khám phá ra nó. Phụ thuộc của nó là các hợp đồng PHP Standard Recommendation (PSR): PSR-18, PSR-17 và PSR-3, cùng với các kiểu config và contract riêng của gói. Bất kỳ framework nào dựng được các thành phần cộng tác đó đều dựng được bộ kết xuất. Gói này chỉ phụ thuộc vào các hợp đồng PSR; bài kiểm thử tests/Unit/Architecture/PsrConformanceTest.php khẳng định rằng không có client cụ thể nào bị gắn chặt vào bộ kết xuất. Ứng dụng chủ của bạn có thể tái sử dụng đăng ký HTTP client hiện có mà không cần thay đổi. Các adapter NextPDF cho Laravel, Symfony và CodeIgniter đều tái sử dụng đúng đăng ký PSR-18 đó. Gói này không bổ sung gói framework riêng nào.

Trình tự khởi động

Phân giải các thành phần cộng tác theo thứ tự sau, tương ứng với hàm khởi tạo của CloudflareHtmlRenderer:

1. Phân giải ClientInterface PSR-18 từ đăng ký HTTP client hiện có của ứng dụng.
2. Phân giải RequestFactoryInterface và StreamFactoryInterface PSR-17; cũng phân giải ResponseFactoryInterface khi bạn muốn dùng transport cURL đã ghim.
3. Dựng một CloudflareRendererConfig từ cấu hình đã phân giải (xem “Thứ tự phân giải cấu hình”).
4. Tùy chọn phân giải một LoggerInterface PSR-3, một LocalRendererFactoryInterface, và một HtmlSecurityPolicyInterface tường minh.
5. Khởi tạo CloudflareHtmlRenderer với những thành phần cộng tác đó.

Không bước nào trong số này kết nối tới mạng. Tương tác mạng đầu tiên chỉ diễn ra khi bạn gọi render() hoặc isAvailable().

Đăng ký trong container

Một đăng ký điển hình (mã giả không phụ thuộc framework):

<?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),
    );
});

Thứ tự phân giải cấu hình

Gói này không tự đọc biến môi trường. Nó nhận một CloudflareRendererConfig đã được dựng đầy đủ. Trong ứng dụng chủ, hãy phân giải cấu hình theo thứ tự sau: trước hết là biến môi trường, rồi đến config đã xuất bản hoặc config của framework, sau đó là các giá trị mặc định của gói được cài sẵn trong hàm khởi tạo (được mô tả trong /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() áp dụng các giá trị mặc định của hàm khởi tạo cho bất kỳ khóa nào bị thiếu hoặc có kiểu không đúng, vì vậy một mảng config thiếu một phần sẽ lùi về giá trị mặc định theo cách có thể dự đoán, thay vì thất bại.

Chẩn đoán

CloudflareRendererConfig::isValid() là tín hiệu tại thời điểm khởi động. Đây là một phép kiểm thuần túy rằng cả workerUrl và apiToken đều không rỗng, đồng thời không thực hiện cuộc gọi mạng nào, vì vậy bạn có thể dùng nó làm cổng kiểm soát triển khai. Tín hiệu tại thời điểm chạy là CloudflareHtmlRenderer::isAvailable(), một yêu cầu HTTP HEAD có xác thực, trả về true đối với trạng thái dưới 500 và false (không bao giờ ném ngoại lệ) trong các trường hợp còn lại, vì vậy bạn có thể dùng nó làm phép thăm dò mức độ sẵn sàng. Một phép thăm dò thành công là một tín hiệu gợi ý, không phải sự bảo đảm: POST tiếp theo vẫn có thể thất bại.

Xem thêm

• /integrations/cloudflare/integration/ — hướng dẫn tích hợp từng bước đầy đủ.
• /integrations/cloudflare/overview/ — cầu nối này là gì và nó vượt qua ranh giới nào.
• /integrations/cloudflare/configuration/ — mọi trường và giá trị mặc định.
• /integrations/cloudflare/security-and-operations/ — khi nào transport đã ghim được kích hoạt.