NextPDF Cloudflare — uruchamianie i wykrywanie

W skrócie

Mostek nie zawiera własnego dostawcy usług, pakietu (bundle) ani mechanizmu automatycznego wykrywania. Jest zestawem klas final z jawnymi konstruktorami. W tym kontekście „wykrywanie” oznacza dobór współpracowników do wstrzyknięcia oraz powiązanie ich w kontenerze frameworka. Ta strona opisuje takie połączenie zależności. Nie zakłada mechanizmu rejestracji, którego pakiet nie posiada.

Jak wykrywany jest mostek renderera

Klasę CloudflareHtmlRenderer tworzysz samodzielnie — nie jest wykrywana automatycznie. Jej zależności to kontrakty PHP Standard Recommendation (PSR): PSR-18, PSR-17 i PSR-3, a także własna konfiguracja oraz typy kontraktów pakietu. Każdy framework, który potrafi zbudować tych współpracowników, potrafi też zbudować renderer. Pakiet zależy wyłącznie od kontraktów PSR; test tests/Unit/Architecture/PsrConformanceTest.php potwierdza, że renderer nie jest sprzężony z żadnym konkretnym klientem. Aplikacja hosta może bez zmian wykorzystać istniejące powiązanie klienta HTTP. Adaptery NextPDF dla Laravel, Symfony i CodeIgniter wykorzystują to samo powiązanie PSR-18. Ten pakiet nie dodaje własnego pakietu frameworkowego.

Sekwencja uruchamiania

Rozwiąż współpracowników w następującej kolejności, zgodnie z kolejnością w konstruktorze klasy CloudflareHtmlRenderer:

1. Rozwiąż interfejs ClientInterface PSR-18 z istniejącego powiązania klienta HTTP aplikacji.
2. Rozwiąż interfejsy RequestFactoryInterface i StreamFactoryInterface PSR-17; rozwiąż także interfejs ResponseFactoryInterface, gdy zamierzasz korzystać z przypiętego transportu cURL.
3. Zbuduj obiekt CloudflareRendererConfig z rozwiązanej konfiguracji (zobacz „Kolejność rozwiązywania konfiguracji”).
4. Opcjonalnie rozwiąż interfejs LoggerInterface PSR-3, interfejs LocalRendererFactoryInterface oraz jawny HtmlSecurityPolicyInterface.
5. Utwórz obiekt CloudflareHtmlRenderer z tymi współpracownikami.

Żaden z tych kroków nie wykonuje połączenia sieciowego. Pierwsza interakcja z siecią następuje przy wywołaniu metody render() lub isAvailable().

Powiązania w kontenerze

Przykładowe powiązanie (pseudokod niezależny od frameworka):

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

Kolejność rozwiązywania konfiguracji

Pakiet sam nie odczytuje zmiennych środowiskowych. Przyjmuje gotowy obiekt CloudflareRendererConfig. W aplikacji hosta rozwiązuj konfigurację w następującej kolejności: najpierw zmienne środowiskowe, następnie opublikowana konfiguracja lub konfiguracja frameworka, a na końcu wartości domyślne pakietu wbudowane w konstruktor (opisane w /integrations/cloudflare/configuration/). CloudflareRendererConfig::fromArray() stosuje wartości domyślne z konstruktora dla każdego brakującego klucza lub klucza o nieprawidłowym typie, dzięki czemu częściowa tablica konfiguracji przewidywalnie korzysta z wartości zastępczych zamiast zgłaszać błąd.

Diagnostyka

CloudflareRendererConfig::isValid() jest sygnałem na etapie uruchamiania. To czyste sprawdzenie, czy zarówno workerUrl, jak i apiToken są niepuste; nie wykonuje żadnego wywołania sieciowego, dlatego możesz użyć go jako bramki wdrożeniowej. Sygnałem czasu działania jest CloudflareHtmlRenderer::isAvailable(): metoda wykonuje uwierzytelnione żądanie HTTP HEAD, zwraca true dla statusu poniżej 500, w przeciwnym razie false, i nigdy nie zgłasza wyjątku. Dlatego możesz użyć jej jako sondy gotowości. Pomyślna sonda jest wskazówką, a nie gwarancją: kolejne żądanie POST nadal może się nie powieść.

Zobacz także

• /integrations/cloudflare/integration/ — pełny przewodnik po integracji.
• /integrations/cloudflare/overview/ — czym jest mostek i jaką granicę przekracza.
• /integrations/cloudflare/configuration/ — każde pole i każda wartość domyślna.
• /integrations/cloudflare/security-and-operations/ — kiedy aktywuje się przypięty transport.