Przewodnik programisty po Gotenberg

W skrócie

Pakiet Gotenberg deleguje konwersję do formatu Portable Document Format (PDF) do zewnętrznej usługi. W kodzie aplikacji utrzymuj wyraźną granicę tej usługi: zweryfikuj dane wejściowe, zbuduj ładunek, wyślij żądanie, przeanalizuj wynik i obsłuż awarię usługi.

Skorzystaj z tego przewodnika, gdy budujesz przepływy konwersji dokumentów biurowych do PDF, punkty końcowe przesyłania, kontrole stanu usługi lub zasady transportu dla nextpdf/gotenberg.

Granica architektury

Warstwa	Właściciel	Odpowiedzialność	Nie umieszczaj tutaj
Źródło przesłanego pliku lub dokumentu	Aplikacja	Autoryzuj wywołującego, zweryfikuj źródło i wybierz zasady konwersji.	Decyzje o punkcie końcowym usługi lub przypinaniu transportu.
Wykrywanie formatu	`nextpdf/gotenberg`	Mapuj bezpieczne rozszerzenia na `OfficeFormat`.	Zaufanie do zadeklarowanych typów multimediów bez weryfikacji w aplikacji.
Most	`nextpdf/gotenberg`	Zbuduj żądanie multipart, wywołaj Gotenberg i przeanalizuj odpowiedź PDF.	Zapytania domenowe lub zasady przechowywania.
Usługa Gotenberg	Wdrożenie	Przekształć dokument biurowy na PDF.	Autoryzacja w aplikacji Hypertext Preprocessor (PHP).
Główny silnik	`nextpdf/nextpdf`	Importuj lub łącz przekonwertowane dane PDF w razie potrzeby.	Konwersja dokumentów biurowych.

Cykl życia w czasie wykonywania

Etap	Zachowanie	Działanie programisty
Tworzenie konfiguracji	Punkt końcowy interfejsu programowania aplikacji (API), limit czasu, maksymalny rozmiar, klucz API i przypięcia są wczytywane z konfiguracji.	Punkt końcowy usługi i token trzymaj poza kodem źródłowym.
Weryfikacja danych wejściowych	Sprawdzane są ścieżka pliku, rozmiar pliku, nazwa pliku, rozszerzenie oraz bezpieczeństwo adresu Uniform Resource Locator (URL).	Odrzuć nieobsługiwane dane wejściowe, zanim je wyślesz.
Konstrukcja ładunku	`GotenbergConvertPayload` buduje dane formularza multipart.	Zachowaj oryginalną nazwę pliku tylko wtedy, gdy jest bezpieczna.
Żądanie usługi	Most wysyła żądanie do `/forms/libreoffice/convert`.	Skonfiguruj limit czasu i zasady transportu.
Analiza wyniku	`GotenbergResponseParser::parse()` zwraca bajty PDF i metadane.	Traktuj odpowiedzi inne niż PDF oraz odpowiedzi z błędem jako niepowodzenia konwersji.

Zalecana struktura aplikacji

Ścieżka	Cel
`app/Pdf/Conversion/*`	Warstwa aplikacji opakowująca `GotenbergBridge`.
`app/Pdf/Uploads/*`	Weryfikacja przesyłania, przechowywanie i zasady nazewnictwa plików.
`app/Pdf/ConversionPolicy/*`	Zasady doboru rozmiaru, formatu i usługi.
`tests/Pdf/Conversion/*`	Testy formatu, pliku, usługi i transportu.

Oddziel weryfikację pliku od konwersji. Usługa konwersji powinna otrzymywać już autoryzowane dane wejściowe, a mimo to nadal korzystać z weryfikacji w pakiecie jako dodatkowej warstwy zabezpieczeń.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

Wzorce konwersji

Wzorzec	API	Stosuj, gdy	Ograniczenie
Konwersja ze ścieżki pliku	`GotenbergBridge::convertFile()`	Dokument jest już zapisany na dysku.	Ścieżka musi być możliwa do odczytu i zatwierdzona przez zasady.
Konwersja bajtów w pamięci	`GotenbergBridge::convertString()`	Aplikacja ma już bajty z przesłanego pliku lub magazynu obiektów.	Nazwa pliku nadal decyduje o wykrywaniu formatu.
Bezpośrednie budowanie ładunku	`GotenbergConvertPayload`	Potrzebujesz bajtów multipart do testów lub własnego kodu transportu.	Generowanie separatora trzymaj poza danymi wejściowymi użytkownika.
Bezpośrednia analiza odpowiedzi	`GotenbergResponseParser::parse()`	Niestandardowe wywołania Hypertext Transfer Protocol (HTTP) nadal wymagają analizy zapewnianej przez pakiet.	Musisz przekazać oczekiwany `OfficeFormat`.

Stan i gotowość

GotenbergBridge::isAvailable() to sygnał gotowości, a nie jedyna ochrona w czasie wykonywania. Usługa może przejść kontrolę gotowości, a mimo to zawieść przy następnej konwersji.

Kontrola	Cel	Uwaga operacyjna
Poprawność konfiguracji	Wykryj brakujący punkt końcowy API.	Wykonuj podczas rozruchu aplikacji lub kontroli wdrożenia.
`/health` – dostępność	Wykryj, czy usługa jest osiągalna.	Stosuj w pulpitach gotowości.
Konwersja małego pliku testowego	Wykryj uszkodzone zachowanie LibreOffice lub regresję usługi.	Uruchamiaj w zaplanowanych testach dymnych, a nie przy każdym żądaniu.
Monitorowanie limitu czasu	Wykryj spowolnienia usługi.	Śledź według formatu i rozmiaru pliku.

Punkty rozszerzeń

Punkt rozszerzenia	Zastosowanie	Ograniczenie
PHP Standard Recommendation (PSR)-18 `ClientInterface`	Niestandardowe zachowanie klienta HTTP.	Musi przestrzegać semantyki odpowiedzi i wyjątków PSR-18.
Fabryki PSR-17	Tworzenie żądań i strumieni.	Wymagane do skonstruowania mostu.
`HtmlSecurityPolicyInterface`	Zasady w warstwie analizy danych wejściowych Hypertext Markup Language (HTML).	Uzupełnia zasady bezpieczeństwa Gotenberg.
`ResponseFactoryInterface`	Konstruowanie odpowiedzi dla przypiętego transportu cURL.	Wymagane tylko wtedy, gdy korzystasz ze ścieżki transportu z pakietu.
`GotenbergSecurityPolicy`	Weryfikacja adresu URL, rozmiaru pliku, nazwy pliku i przypięć.	Autoryzację aplikacji trzymaj poza tą warstwą.

Proces programistyczny

Zacznij od convertString() w testach, aby pliki testowe były jawne.
Dodaj convertFile() dopiero wtedy, gdy ścieżki systemu plików są objęte kontrolą.
Ustawiaj maksymalny rozmiar pliku poniżej limitów usługi i infrastruktury.
Używaj isAvailable() do sygnałów gotowości, a nie jako zamiennika obsługi błędów.
Rejestruj nazwę pliku, format, rozmiar, status i czas trwania. Nie rejestruj bajtów dokumentu.
Dodaj testy limitu czasu i trybów awarii, zanim udostępnisz punkty końcowe przesyłania.

Obsługa awarii

Awaria	Gdzie należy ją obsłużyć	Zalecana reakcja
Nieobsługiwane rozszerzenie	Wykrywanie formatu.	Odrzuć, zanim wyślesz do usługi.
Niebezpieczna nazwa pliku	Zasady bezpieczeństwa.	Odrzuć ją i zastosuj spójne zasady nazewnictwa przesyłanych plików.
Plik o nadmiernym rozmiarze	Zasady przesyłania i weryfikacja w pakiecie.	Odrzuć, zanim odczytasz lub wyślesz duże ładunki.
Gotenberg niedostępny	Granica mostu.	Zwróć ponawialny błąd aplikacji, gdy jest to właściwe.
Odpowiedź inna niż PDF	Analizator odpowiedzi.	Potraktuj to jako niepowodzenie konwersji i zarejestruj status usługi.
Niepowodzenie weryfikacji przypięcia lub adresu URL	Zasady transportu.	Zablokuj awaryjnie i powiadom operatorów.

Bezpieczne wartości domyślne

Zagadnienie	Wartość domyślna	Kiedy zmienić
Limit czasu	`30` sekund.	Zwiększaj dopiero po zmierzeniu rzeczywistego opóźnienia usługi.
Maksymalny rozmiar pliku	`52,428,800` bajtów.	Zmniejsz dla publicznych lub wielodostępnych punktów końcowych.
Klucz API	Pusty.	Ustaw dla prywatnych wdrożeń Gotenberg.
Obsługiwane formaty	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Dodawaj formaty tylko wtedy, gdy `OfficeFormat` i analizator je obsługują.
Zestawy przypięć	Pusty.	Dodawaj przypięcia wraz z zapasowymi przypięciami i procedurą rotacji.

Lista kontrolna testów

Testy formatu obejmują obsługiwane i nieobsługiwane rozszerzenia.
Testy plików obejmują brakujące pliki, pliki niemożliwe do odczytu, pliki o nadmiernym rozmiarze i niebezpieczne nazwy plików.
Testy usługi obejmują odpowiedzi inne niż 2xx, nieprawidłowe treści odpowiedzi i wyjątki transportu.
Testy bezpieczeństwa obejmują prywatne lub nieprawidłowe adresy URL usługi, gdy zabraniają ich zasady.
Testy limitu czasu potwierdzają, że skonfigurowany limit czasu jest przekazywany do transportu.
W testach z plikami testowymi dbaj, aby przykładowe dokumenty były małe i nie zawierały danych wrażliwych.