Dokumentacja API Gotenberg

W skrócie

Pakiet Gotenberg udostępnia pojedynczy mostek do usługi, GotenbergBridge. Konwertuje dokument Office (docx, xlsx, pptx, odt, ods, odp) do formatu PDF (Portable Document Format), wysyłając żądanie POST do zewnętrznej usługi Gotenberg. Mostek współpracuje z obiektami wartości, które przekazujesz albo odczytujesz: GotenbergConfig (niezmienny deskryptor usługi wraz z limitami), OfficeFormat (typ wyliczeniowy dla obsługiwanych formatów), GotenbergConvertPayload (treść żądania w formacie multipart) oraz GotenbergConvertResult (przetworzona odpowiedź PDF). Druga warstwa — GotenbergSecurityPolicy, GotenbergResponseParser oraz PinnedCurlTransport — zapewnia walidację, analizę składniową i transport z przypinaniem, którymi mostek steruje wewnętrznie. Używaj tej warstwy tylko wtedy, gdy piszesz niestandardowy transport lub kod testowy.

Zacznij tutaj: utwórz obiekt GotenbergConfig z adresem URL usługi używającym Hypertext Transfer Protocol Secure (HTTPS), a następnie przekaż go do GotenbergBridge wraz z klientem PSR-18 i fabrykami PSR-17. Wywołaj metodę convertFile() lub convertString(), a potem odczytaj pdfData ze zwróconego obiektu GotenbergConvertResult.

Typowe zadania

Do najczęstszych zadań w tym pakiecie używaj tych zweryfikowanych, gotowych do uruchomienia fragmentów kodu.

Konwertowanie pliku z dysku do formatu PDF

Przekaż mostkowi ścieżkę. Format zostanie wykryty na podstawie rozszerzenia.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

Co robi: weryfikuje adres URL, ścieżkę, rozmiar i nazwę pliku; wysyła jedno żądanie multipart; zapisuje zwrócone bajty PDF na dysku.

Konwertowanie bajtów z pamięci do formatu PDF

Użyj metody convertString(), gdy masz już bajty w pamięci. Format jest wykrywany na podstawie nazwy pliku.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

if (! $result->isValid()) {
    throw new \RuntimeException('Conversion did not return a valid PDF.');
}

Co robi: wykrywa format xlsx na podstawie nazwy pliku, konwertuje bajty i przed użyciem wyniku potwierdza, że zaczyna się on od sygnatury %PDF.

Sprawdzanie gotowości usługi przed konwersją

Przed konwersją użyj metody isAvailable(). Sprawdza adres URL bez ruchu sieciowego, a następnie wysyła jedno żądanie HEAD do /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Co robi: zwraca false (nigdy nie zgłasza wyjątku), gdy adres URL jest pusty, nie używa HTTPS, jest prywatny albo gdy wystąpi dowolny błąd sieci, dzięki czemu możesz szybko przerwać działanie przed wysłaniem konwersji.

Mostek

Ta tabela opisuje interfejs mostka. Używaj jej podczas konstruowania obiektu GotenbergBridge oraz wywoływania jego metod konwersji i sprawdzania gotowości.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Konfiguracja, klient PSR-18, fabryki PSR-17, opcjonalny rejestrator, opcjonalna polityka HTML, opcjonalna fabryka odpowiedzi.	Używa `DefaultHtmlSecurityPolicy`, jeśli nie podasz własnej polityki.	`GotenbergBridge`	Błędy konfiguracji kontenera.	Fabryka odpowiedzi włącza transport cURL z przypinaniem, gdy przypinanie jest wymagane.
`GotenbergBridge::convertFile(string $filePath)`	Ścieżka do dokumentu Office w systemie plików.	Wykrywa format na podstawie rozszerzenia pliku.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` dla nieobsługiwanego formatu.	Ustala rzeczywistą ścieżkę oraz sprawdza możliwość odczytu, rozmiar i nazwę pliku.
`GotenbergBridge::convertString(string $content, string $fileName)`	Surowe bajty i oryginalna nazwa pliku.	Wykrywa format na podstawie rozszerzenia nazwy pliku.	`GotenbergConvertResult`	Tak samo jak `convertFile`.	Używaj, gdy aplikacja ma już bajty pliku.
`GotenbergBridge::isAvailable()`	brak.	Wysyła żądanie HEAD do `/health`, gdy konfiguracja jest prawidłowa.	`bool`	Zwraca `false` w przypadku błędów.	Służy wyłącznie jako sygnał gotowości.
`GotenbergBridge::getHtmlSecurityPolicy()`	brak.	Zwraca skonfigurowaną politykę dla warstwy analizy składniowej.	`HtmlSecurityPolicyInterface`	brak oczekiwanych.	Uzupełnia politykę bezpieczeństwa na poziomie transportu.

Konfiguracja i ładunki

Ta tabela opisuje obiekty wartości tworzone bezpośrednio: deskryptor usługi GotenbergConfig oraz nośniki żądania i odpowiedzi GotenbergConvertPayload/GotenbergConvertResult. Używaj ich, gdy potrzebujesz bardziej szczegółowej kontroli niż ta zapewniana przez dwa punkty wejścia konwersji.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	Adres URL API, limit czasu, maksymalny rozmiar pliku, token bearer, zestawy przypięć.	Pusty adres URL jest nieprawidłowy; domyślny maksymalny rozmiar to 50 MiB.	`GotenbergConfig`	brak oczekiwanych.	Trzymaj klucz API w tajemnicy.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, tablice przypięć.	Brakujące pola opcjonalne przyjmują wartości domyślne z konstruktora.	`GotenbergConfig`	brak oczekiwanych.	Listy ciągów znaków pomijają wartości, które nie są ciągami znaków.
`GotenbergConfig::isValid()`	brak.	Uznaje konfigurację za prawidłową, gdy adres URL API nie jest pusty.	`bool`	brak oczekiwanych.	Bezpieczeństwo adresu URL jest sprawdzane przed jakąkolwiek operacją sieciową.
`GotenbergConfig::allPublicKeyPins()`	brak.	Łączy przypięcia podstawowe i zapasowe.	`list<string>`	brak oczekiwanych.	Pusta lista wyłącza przypinanie.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nazwa pliku, bajty, format, flaga orientacji, zakresy stron.	Orientacja pionowa; wszystkie strony.	`GotenbergConvertPayload`	brak oczekiwanych.	Ładunek jest zamieniany na dane formularza w formacie multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Granica multipart.	Dodaje pole zakresu stron tylko wtedy, gdy nie jest puste.	`string`	brak oczekiwanych.	Mostek generuje granicę.
`GotenbergConvertPayload::contentType(string $boundary)`	Granica multipart.	Używa `multipart/form-data`.	`string`	brak oczekiwanych.	Dołącz jako `Content-Type` w żądaniu.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Przekonwertowane bajty PDF, format źródłowy, opcjonalny czas renderowania.	Czas renderowania wynosi `0.0`, jeśli nie jest mierzony.	`GotenbergConvertResult`	brak oczekiwanych.	Zwracane przez `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	brak.	Wynik jest prawidłowy, gdy przekonwertowane bajty PDF nie są puste i wyglądają jak dane PDF.	`bool`	brak oczekiwanych.	Sprawdź przed zapisaniem lub strumieniowaniem wyniku.
`GotenbergConvertResult::size()`	brak.	Zwraca liczbę przekonwertowanych bajtów PDF.	`int`	brak oczekiwanych.	Używaj tej wartości do limitów, telemetrii i ograniczeń odpowiedzi.

Formaty Office

Ta tabela opisuje typ wyliczeniowy OfficeFormat. Używaj go do mapowania rozszerzenia na format, odczytywania jego typu MIME przesyłania albo sprawdzania, które sześć formatów jest obsługiwanych.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`OfficeFormat::fromExtension(string $ext)`	Rozszerzenie pliku z wiodącą kropką lub bez niej.	Dopasowuje z pominięciem wielkości liter.	`OfficeFormat`	`ValueError` dla nieobsługiwanego rozszerzenia.	Obsługiwane wartości: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	brak.	Mapuje przypadek typu wyliczeniowego na typ MIME używany przy przesyłaniu.	`string`	brak oczekiwanych.	Używany w części plikowej formularza multipart.
`OfficeFormat::extension()`	brak.	Zwraca wartość bazową.	`string`	brak oczekiwanych.	Przydatny w diagnostyce i nazwach plików.

Bezpieczeństwo, analiza składniowa i transport

Ta tabela opisuje wewnętrzne mechanizmy, którymi mostek zarządza za ciebie. Używaj jej tylko wtedy, gdy piszesz niestandardowy transport, wykonujesz niestandardowe wywołanie Hypertext Transfer Protocol (HTTP), które nadal wymaga analizy składniowej zapewnianej przez pakiet, albo badasz niskopoziomowe zachowanie bezpieczeństwa i przypinania.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	Bazowy adres URL API.	Analizuje miejsce docelowe i sprawdza je przed jakąkolwiek operacją sieciową.	`array`	`RuntimeException` dla niebezpiecznych lub nieprawidłowych adresów URL.	Chroni kod konwersji przed błędami punktów końcowych typu server-side request forgery (SSRF).
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host oraz lista przypiętych adresów Internet Protocol (IP).	Weryfikuje oczekiwania wobec przypięć Domain Name System (DNS).	`void`	`RuntimeException`, gdy przypięcia są nieaktualne lub nieprawidłowe.	Używaj we wdrożeniach z przypinaniem oraz w diagnostyce operacyjnej.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Rzeczywisty rozmiar i skonfigurowane maksimum.	Akceptuje pliki o rozmiarze nie większym niż skonfigurowany limit.	`void`	`RuntimeException`, gdy plik jest zbyt duży.	Egzekwuj przed zbudowaniem żądania.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Oryginalna nazwa pliku.	Odrzuca niebezpieczne lub nieobsługiwane formy nazw plików.	`void`	`RuntimeException` dla nieprawidłowych nazw.	Zapobiega zniekształceniu nazw plików w formularzu multipart.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Odpowiedź PSR-7 i oczekiwany format Office.	Wyodrębnia przekonwertowane bajty PDF z udanej odpowiedzi.	`GotenbergConvertResult`	`GotenbergConvertException` w przypadku nieudanych odpowiedzi lub nieprawidłowego wyniku PDF.	Centralny parser używany przy konwersji plików i ciągów znaków.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Fabryki PSR-17, przypięte adresy IP, przypięte klucze publiczne, limit czasu.	Brak przypięć i 30-sekundowy limit czasu.	`PinnedCurlTransport`	brak oczekiwanych.	Używaj tylko wtedy, gdy wymagane jest przypinanie na poziomie cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Żądanie PSR-7.	Wysyła przez cURL z ustawionym limitem czasu i mechanizmami przypinania.	`ResponseInterface`	`GotenbergConvertException` w przypadku niepowodzenia cURL/transportu.	Używaj, gdy przypinania nie można delegować do innego klienta HTTP.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Żądanie, host i port.	Buduje tablicę opcji cURL używaną przez `sendRequest()`.	`array`	Błędy związane z nieprawidłowym żądaniem lub konfiguracją przypięć.	Niskopoziomowa diagnostyka oraz punkt zaczepienia dla testów.

Uwagi dla programistów

Traktuj Gotenberg jako granicę usługi zewnętrznej. Świadomie ustawiaj limit czasu, rozmiar, adres URL i politykę przypinania.
convertFile() wczytuje cały plik do pamięci przed zbudowaniem żądania.
Rejestruj metadane, takie jak nazwa pliku i długość treści, a nie zawartość pliku.