Integracja NextPDF z Gotenberg

W skrócie

Ta strona pokazuje, jak podłączyć mostek do reszty aplikacji. Zainstaluj go, skonfiguruj połączenie z aplikacją, a następnie przekaż przekonwertowany plik w formacie Portable Document Format (PDF) do potoku przetwarzania końcowego NextPDF. Mostek konwertuje dokument Office na PDF; potok przejmuje wszystko, co dzieje się po konwersji. Aby poznać założenia stojące za tym połączeniem, zobacz /integrations/gotenberg/boot-and-discovery/.

Instalacja

composer require nextpdf/gotenberg

Wraz z tym pakietem instalowane są także nextpdf/core ^3.0 oraz kontrakty PHP Standards Recommendation (PSR) dla Hypertext Transfer Protocol (HTTP). Klienta PSR-18 i fabryki PSR-17 zainstaluj jako osobne pakiety. Mostek zależy wyłącznie od interfejsów, dzięki czemu możesz wybrać konkretne biblioteki. Pełne kroki instalacji, w tym sposób uruchomienia usługi Gotenberg przez Hypertext Transfer Protocol Secure (HTTPS), znajdziesz w /integrations/gotenberg/install/.

Łączenie

Utwórz mostek za pomocą obiektu konfiguracji oraz zależności PSR. Wstrzyknij także fabrykę odpowiedzi; włącza ona transport z przypinaniem Domain Name System (DNS) i przypinaniem Transport Layer Security (TLS):

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

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Mostek wymaga HTTPS pod skonfigurowanym adresem URL. Odrzuca zwykłe http://, zanim wyśle jakiekolwiek żądanie. Uruchom Gotenberg za terminacją TLS, a następnie skieruj mostek na punkt końcowy HTTPS.

Powiązania w kontenerze

Zarejestruj trzy wpisy w kontenerze hosta: GotenbergConfig zbudowany ze źródła konfiguracji, klienta PSR-18 wraz z fabrykami PSR-17 oraz GotenbergBridge złożony z tych zależności. Ten pakiet nie dostarcza własnych powiązań. Natywna rejestracja w frameworkach należy do dedykowanych pakietów integracyjnych. Zobacz /integrations/gotenberg/boot-and-discovery/.

Konfiguracja

W GotenbergConfig znajdują się wszystkie pola deskryptora usługi i limity. Obejmują one adres URL dla application programming interface (API), limit czasu, limit rozmiaru, token bearer oraz przypięcia TLS. Opcje ustawiane dla pojedynczego żądania, landscape i nativePageRanges, znajdują się natomiast w typie ładunku. /integrations/gotenberg/configuration/ dokumentuje każde pole, jego typ, wartość domyślną i działanie.

Dołączanie przekonwertowanego pliku PDF do potoku NextPDF

Typowy przepływ od początku do końca:

1. Przekonwertuj dokument Office za pomocą convertFile() lub convertString().
2. Pobierz dane z $result->pdfData, które zawierają surowe bajty PDF, i wczytaj je do dokumentu NextPDF.
3. Zastosuj przetwarzanie końcowe, takie jak składanie stron, znaki wodne, konwersja PDF/A lub podpisy cyfrowe.

Krok 3 należy do NextPDF, a nie do mostka. Pakiet nextpdf/premium zapewnia podpisywanie, profile PDF/A oraz znaki wodne. Traktuj konwersję i przetwarzanie końcowe jako osobne etapy, aby móc diagnozować każdą awarię oddzielnie.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Obsługa PDF Advanced Electronic Signatures (PAdES) w edycji Pro obejmuje wyłącznie poziom bazowy B-B. Nie obejmuje B-T, B-LT ani B-LTA. Konwersja dokumentu przez ten mostek nie oznacza możliwości znakowania czasem ani walidacji długoterminowej.

Test dymny

Po połączeniu potwierdź integrację bez konwertowania prawdziwego dokumentu:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() najpierw sprawdza adres URL bez ruchu sieciowego. Następnie wysyła żądanie HEAD do <apiUrl>/health. Potem przekonwertuj jeden niewielki dokument o znanej poprawności. Przećwiczy to pełną ścieżkę multipart do <apiUrl>/forms/libreoffice/convert i zweryfikuje odpowiedź.

Punkty wejścia publicznego API

Publiczny interfejs, z którego korzysta ta integracja:

• GotenbergConfig — niezmienny deskryptor usługi oraz limity; fromArray() buduje go z tablicy konfiguracji.
• GotenbergBridge::convertFile(string $path) — konwertuje plik na dysku.
• GotenbergBridge::convertString(string $bytes, string $fileName) — konwertuje bajty przechowywane w pamięci.
• GotenbergBridge::isAvailable() — sonda gotowości niezgłaszająca wyjątków.
• GotenbergConvertResult — zawiera pdfData, sourceFormat, isValid() oraz size().
• GotenbergConvertException — typ wyjątku warstwy konwersji.

Pełny kontrakt znajdziesz w /integrations/gotenberg/configuration/ oraz /integrations/gotenberg/troubleshooting/. Obejmuje wybór transportu oraz katalog wyjątków.

Zobacz też

• /integrations/gotenberg/boot-and-discovery/ — dlaczego połączenie wygląda właśnie tak.
• /integrations/gotenberg/quickstart/ — pierwsza konwersja krok po kroku.
• /integrations/gotenberg/production-usage/ — sekrety, ponawianie prób, limity czasu i obserwowalność.
• /integrations/gotenberg/install/ — instalacja pakietu i usługi Gotenberg.