Konfiguracja NextPDF Gotenberg

W skrócie

Konfiguracja składa się z dwóch części: niezmiennego obiektu wartości GotenbergConfig, który opisuje usługę i jej limity, oraz argumentów konstruktora GotenbergBridge, który przyjmuje zależności PHP Standard Recommendation (PSR) dla Hypertext Transfer Protocol (HTTP). Oba elementy przekazujesz jawnie przez konstruktor. Pakiet nie ma globalnego stanu, nie odczytuje zmiennych środowiskowych i nie definiuje żadnego ukrytego domyślnego punktu końcowego.

Obiekt konfiguracji

GotenbergConfig to obiekt wartości final readonly. Utwórz go bezpośrednio, używając argumentów nazwanych, albo zbuduj z tablicy asocjacyjnej metodą GotenbergConfig::fromArray().

Pola

Pole	Typ	Wartość domyślna	Efekt
apiUrl	string	''	Bazowy Uniform Resource Locator (URL) usługi Gotenberg. Wymagane: pusta wartość powoduje, że konfiguracja jest nieprawidłowa, a każda konwersja kończy się natychmiastowym niepowodzeniem. Musi używać Hypertext Transfer Protocol Secure (HTTPS).
timeout	int	30	Twardy limit czasu przesyłania w sekundach. Transport cURL z przypinaniem stosuje go, gdy jest używany.
maxFileSize	int	52_428_800	Maksymalny rozmiar danych wejściowych w bajtach (50 MiB). Dane wejściowe większe niż ta wartość są odrzucane przed jakimkolwiek żądaniem.
apiKey	string	''	Token bearer. Gdy jest niepusty, jest wysyłany jako nagłówek Authorization: Bearer <token>. Oznaczony jako #[\SensitiveParameter], dzięki czemu jest ukrywany w śladach stosu.
pinnedPublicKeys	list<string>	[]	Podstawowe przypięcia Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) w postaci sha256/<base64>. Wartość pusta wyłącza przypinanie.
backupPublicKeys	list<string>	[]	Zapasowe przypięcia TLS SPKI, przechowywane osobno, aby rotację można było weryfikować niezależnie.

Tworzenie bezpośrednie

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

Tworzenie z tablicy

fromArray() przyjmuje klucze w formacie snake_case i ignoruje nieprawidłowe wartości, zamiast zgłaszać wyjątek. Wartość api_url, która nie jest łańcuchem znaków, staje się ''. Wartość timeout, która nie jest liczbą całkowitą, wraca do 30. Wartość max_file_size, która nie jest liczbą całkowitą, wraca do domyślnej wartości 50 MiB. Listy przypięć, które nie są tablicami, stają się []. Wpisy, które nie są łańcuchami znaków, wewnątrz tablic przypięć są pomijane.

<?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='],
]);

Takie łagodne parsowanie jest zamierzone. Możesz przekazać tablicę konfiguracji frameworka bezpośrednio, bez warstwy wstępnej walidacji, a mimo to otrzymać obiekt ze ściśle określonymi typami. Parsowanie nie weryfikuje, czy adres URL jest osiągalny ani czy przypięcia są poprawne. Mostek wykonuje te kontrole w czasie konwersji.

Prawidłowość

isValid() zwraca true tylko wtedy, gdy apiUrl jest niepustym łańcuchem znaków. Nie wykonuje żadnych kontroli sieciowych ani kontroli schematu. Polityka bezpieczeństwa obsługuje HTTPS oraz weryfikację adresów prywatnych w czasie konwersji. Jeśli konfiguracja jest nieprawidłowa, convertFile() i convertString() zgłaszają wyjątek GotenbergConvertException z komunikatem Invalid Gotenberg configuration: apiUrl is empty. Nieprawidłowa konfiguracja powoduje też, że isAvailable() zwraca false bez żadnego wywołania sieciowego.

Konstruktor mostka

GotenbergBridge przyjmuje konfigurację oraz zależności PSR:

Argument	Typ	Wymagany	Efekt
config	GotenbergConfig	tak	Deskryptor usługi i limity opisane powyżej.
httpClient	Psr\Http\Client\ClientInterface	tak	Klient PSR-18 używany do sprawdzania stanu usługi i transportu zapasowego.
requestFactory	Psr\Http\Message\RequestFactoryInterface	tak	Buduje żądanie PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	tak	Buduje strumień treści żądania.
logger	Psr\Log\LoggerInterface|null	nie (domyślnie null)	Gdy zostanie dostarczony, zapisuje jeden wpis na poziomie debug dla każdego żądania konwersji.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	nie	Domyślnie używa podstawowej polityki bezpieczeństwa Hypertext Markup Language (HTML). Działa w warstwie parsowania i uzupełnia politykę warstwy transportowej.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	nie (domyślnie null)	Wymagany do aktywacji transportu cURL z przypinaniem. Bez niego mostek zawsze używa wstrzykniętego klienta 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,
);

Wybór transportu

Mostek obsługuje dwa transporty i wybiera jeden z nich dla każdego żądania konwersji:

• Transport cURL z przypinaniem — używany, gdy wstrzyknięto responseFactory oraz dostępne są dane do przypięcia (adres URL rozwiązał się na jeden lub więcej adresów Internet Protocol (IP) albo skonfigurowano przypięcia SPKI). Ten transport wiąże ustalony zestaw adresów za pomocą CURLOPT_RESOLVE. Wymusza przypinanie SPKI za pomocą CURLOPT_PINNEDPUBLICKEY, gdy przypięcia są obecne. Weryfikuje peera i hosta (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Stosuje skonfigurowany limit czasu i wyłącza śledzenie przekierowań (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Wstrzyknięty klient PSR-18 — używany w każdym innym przypadku, w tym gdy adres URL interfejsu programowania aplikacji (API) jest publicznym literałem IP (brak Domain Name System (DNS) do przypięcia) i nie skonfigurowano przypięć SPKI lub gdy nie dostarczono responseFactory.

Aby uzyskać połączenia odporne na ponowne wiązanie DNS i korzystające z przypinania TLS, wstrzyknij responseFactory i skonfiguruj przypięcia. Sprawdzanie stanu usługi zawsze używa wstrzykniętego klienta PSR-18, niezależnie od wyboru transportu.

Przypinanie klucza publicznego TLS

Przypinanie korzysta z modelu odcisku palca SPKI Secure Hash Algorithm 256-bit (SHA-256). Każde przypięcie jest łańcuchem znaków w postaci sha256/<base64-encoded-spki-hash>. Transport akceptuje również natywną dla cURL postać sha256//<base64> i przekształca wariant z pojedynczym ukośnikiem do tej formy. Każdy inny przedrostek powoduje wyjątek InvalidSpkiPinException.

allPublicKeyPins() zwraca sumę zbiorów pinnedPublicKeys i backupPublicKeys bez duplikatów. Warstwa TLS akceptuje certyfikat, którego skrót SPKI pasuje do dowolnego elementu tego połączonego zbioru. Na potrzeby eksploatacji skonfiguruj co najmniej jedno przypięcie zapasowe, aby planowana rotacja certyfikatu lub klucza nie zablokowała dostępu mostka do usługi w czasie propagacji nowego klucza. Przechowywanie listy zapasowej osobno od listy podstawowej pozwala weryfikować i rotować przypięcie zapasowe niezależnie od aktywnego. Procedurę rotacji opisano w /integrations/gotenberg/security-and-operations/.

Opcje konwersji dla pojedynczego żądania

Typ ładunku multipart (GotenbergConvertPayload) przekazuje plik oraz dwie opcjonalne opcje konwersji Gotenberg:

• landscape (bool, domyślnie false) — wysyłane jako pole formularza landscape z wartością "true" lub "false".
• nativePageRanges (string, domyślnie '') — wysyłane jako pole formularza nativePageRanges tylko wtedy, gdy jest niepuste; przyjmuje składnię zakresów Gotenberg, taką jak 1-3 lub 1,3,5-9.

Publiczne punkty wejścia convertFile() i convertString() budują ładunek z wartościami domyślnymi dla obu pól. Pola te są częścią kontraktu ładunku i są sprawdzane przez zestaw testów. Udostępnij je w swojej warstwie integracji, jeśli potrzebujesz wydruku poziomego lub wyboru stron.

Zobacz też

• /integrations/gotenberg/install/ — instalacja i podstawowa konfiguracja Gotenberg.
• /integrations/gotenberg/quickstart/ — kompletny przykład gotowy do uruchomienia.
• /integrations/gotenberg/production-usage/ — ładowanie konfiguracji, sekrety, limity czasu, ponawianie.
• /integrations/gotenberg/security-and-operations/ — pełny model bezpieczeństwa i rotacja przypięć.
• /integrations/gotenberg/troubleshooting/ — wyjaśnienie wyjątków związanych z konfiguracją.