Instalacja NextPDF Gotenberg

W skrócie

Instalacja mostka obejmuje dwie części: pakiet PHP wraz z zależnościami HTTP zgodnymi z PHP Standard Recommendation (PSR), instalowanymi za pomocą Composera, oraz usługę Gotenberg, którą pakiet wywołuje. Mostek konwertuje pliki, przekazując zadanie tej usłudze, więc nie wykona żadnej konwersji, dopóki instancja Gotenberg nie będzie osiągalna.

Wykonaj oba kroki, zanim napiszesz kod konwersji.

Wymagania

Wymaganie	Ograniczenie	Dlaczego
PHP	>=8.4 <9.0	Zadeklarowane przez pakiet w pliku composer.json.
NextPDF core	^3.0	Zadeklarowane jako bezpośrednia zależność w pliku composer.json.
Klient HTTP PSR-18	^1.0	Mostek wysyła żądania przez wstrzykiwany Psr\Http\Client\ClientInterface.
Fabryki HTTP PSR-17	^1.1	Mostek tworzy żądania i strumienie za pomocą wstrzykiwanych fabryk PSR-17.
Rejestrator PSR-3	^3.0 (opcjonalnie)	Można wstrzyknąć rejestrator do zapisywania informacji debugowania na poziomie żądania.
Usługa Gotenberg	Osiągalna przez HTTPS	Konwersję wykonuje usługa zewnętrzna; ten pakiet jej nie przeprowadza.

Mostek nie zawiera wbudowanego klienta PSR-18 ani fabryk PSR-17. Wybierz implementacje odpowiednie dla aplikacji. Na przykład połącz klienta opartego na Guzzle z odpowiadającymi mu fabrykami PSR-17 albo użyj klienta HTTP Symfony z nyholm/psr7. Działa każda implementacja zgodna z właściwymi kontraktami PSR, ponieważ mostek zależy od interfejsów, a nie od konkretnej biblioteki.

Krok 1 — zainstaluj pakiet

Dodaj pakiet za pomocą Composera:

composer require nextpdf/gotenberg

Composer rozwiązuje zależność od nextpdf/core ^3.0 oraz kontrakty PSR dla HTTP: psr/http-client, psr/http-factory oraz psr/log. Nie instaluje konkretnego klienta HTTP.

Krok 2 — zainstaluj klienta PSR-18 i fabryki PSR-17

Zainstaluj jednego klienta PSR-18 i zgodny zestaw fabryk PSR-17. W przypadku Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Albo dla klienta HTTP Symfony i Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Przekaż te implementacje do konstruktora mostka. Mostek nigdy sam nie tworzy klienta HTTP. Implementację wybierasz podczas składania mostka. Kształt konstruktora znajdziesz na stronie /integrations/gotenberg/configuration/, a pełny przykład połączenia — na stronie /integrations/gotenberg/quickstart/.

Krok 3 — uruchom usługę Gotenberg

Mostek wywołuje trasę konwersji LibreOffice w usłudze Gotenberg, więc uruchom instancję Gotenberg, z którą mostek może się połączyć. Projekt źródłowy publikuje obraz kontenera. Do programowania lokalnego użyj:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Dzięki temu Gotenberg jest dostępny na porcie 3000 przez zwykły protokół HTTP. Używaj tego wyłącznie do programowania lokalnego. Mostek wymaga HTTPS dla skonfigurowanego adresu URL API i odrzuca zwykły http://, zanim wyśle jakiekolwiek żądanie. W każdym przypadku poza lokalnym eksperymentem umieść Gotenberg za odwrotnym serwerem proxy albo siatką usług, które terminują Transport Layer Security (TLS), a następnie skieruj mostek na punkt końcowy HTTPS. Strona /integrations/gotenberg/security-and-operations/ opisuje kształt wdrożenia produkcyjnego, ekspozycję sieciową oraz uwierzytelnianie.

Pokazany tutaj znacznik obrazu (gotenberg/gotenberg:8) wskazuje źródłową główną linię Gotenberg. Plik README tego projektu oraz bazowa konfiguracja integracji odwołują się do tej linii. W środowisku produkcyjnym przypnij konkretny znacznik łatki, zamiast śledzić zmieniający się znacznik głównej linii. Zweryfikuj również ścieżki tras (/forms/libreoffice/convert, /health) względem wdrażanej wersji Gotenberg. Mostek zakłada istnienie tych dwóch ścieżek i nie przyjmuje żadnych innych założeń dotyczących usługi.

Krok 4 — zweryfikuj połączenie

Na tym etapie pakiet i klient HTTP są zainstalowane, a Gotenberg jest osiągalny przez HTTPS. Zanim uruchomisz właściwą konwersję, potwierdź za pomocą wbudowanej sondy kondycji, że mostek może połączyć się z usługą:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(apiUrl: 'https://gotenberg.example.com');

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

Metoda isAvailable() najpierw weryfikuje skonfigurowany adres URL. Zwraca false dla pustego adresu URL, adresu URL bez HTTPS albo adresu URL wskazującego adres prywatny bez wysyłania ruchu sieciowego. Następnie wysyła żądanie HEAD do <apiUrl>/health i zgłasza usługę jako dostępną, gdy status jest niższy niż 500. W razie błędu sieci mostek przechwytuje go i zgłasza usługę jako niedostępną zamiast rzucać wyjątek.

Uwaga o wersji

Ta dokumentacja opisuje pakiet z linii ^3.0. Jest ona zgodna z wymaganiem w composer.json oraz z macierzą wsparcia w SECURITY.md, gdzie linia 3.x jest wspierana, a 2.x nie. Wcześniejsze odwołania do 0.x na szkieletowych stronach w repozytorium pochodzą sprzed linii 3.0. Ograniczenie z composer.json ma przed nimi pierwszeństwo.

Zobacz także

• /integrations/gotenberg/overview/ — co robi mostek i które formaty konwertuje.
• /integrations/gotenberg/configuration/ — wszystkie argumenty konstruktora i pola konfiguracji.
• /integrations/gotenberg/quickstart/ — kompletna pierwsza konwersja gotowa do uruchomienia.
• /integrations/gotenberg/security-and-operations/ — bezpieczna obsługa zależności od Gotenberg.
• /integrations/gotenberg/boot-and-discovery/ — automatyczne łączenie we frameworku.